> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vorel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect an AI client to your workspace over the Model Context Protocol: tools, scopes, the read-only endpoint, and prompts.

Vorel exposes your workspace over the Model Context Protocol, so an AI client can query your
conversations, customers, knowledge and analytics directly rather than through screenshots and
copy-paste.

## Endpoints

| Endpoint                                | Tools available                                       |
| --------------------------------------- | ----------------------------------------------------- |
| `https://app.vorel.ai/api/mcp`          | Read tools, plus write tools when the key allows them |
| `https://app.vorel.ai/api/mcp/readonly` | Read tools only                                       |

The read-only endpoint does not merely refuse write calls. The write tools are structurally absent
from it, so no scope, flag or bug can surface one there.

## Authentication

Two ways to connect.

**API key.** Issue a key with the `assistant:read` scope under **Settings, then Integrations, then
API keys**, and send it as a bearer token. Add `assistant:write` only if you want the client to be
able to act.

**OAuth.** Where your client supports it, connect through OAuth instead, which means each person's
actions are attributed to them rather than to a shared key.

<Warning>
  A key carrying `assistant:write` lets whatever AI client holds it pause your agent and message real
  customers, with no human between the model deciding and the action landing. Issue write keys
  deliberately, and consider requiring [approvals](/assistants/governance).
</Warning>

## Read tools

| Tool                          | Returns                                                                                |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `search_tenant_records`       | Conversations, customers, leads, appointments                                          |
| `get_conversation_transcript` | The full transcript of one conversation                                                |
| `search_knowledge`            | Matching knowledge entries                                                             |
| `query_analytics`             | Metrics over a window                                                                  |
| `get_tenant_overview`         | The current state of the workspace                                                     |
| `whoami`                      | Which workspace, which scopes, which endpoint, and the rate limits in force            |
| `list_capabilities`           | Which channels are live, your business hours, and what the assistant can and cannot do |
| `search_vorel_docs`           | These docs, so a client can answer "how do I" questions with citations                 |
| `ask_vorel`                   | One collected answer to a natural-language question, using the tools above             |
| `send_vorel_mcp_feedback`     | Sends us feedback about the MCP surface                                                |

`ask_vorel` is the thick one. The others return data for the client's own model to reason over;
`ask_vorel` runs a full turn inside Vorel and returns a written answer.

The list and search tools accept a `response_format` of `concise` or `detailed`, and a
`max_results`. Concise is the default and costs roughly a third of the tokens. Where a cap trims
results, the response says so and tells the model how to narrow the query, instead of silently
truncating.

## Write tools

Available only with `assistant:write`, and only when write actions are enabled for your workspace:

| Tool                     | Does                                           |
| ------------------------ | ---------------------------------------------- |
| `acknowledge_escalation` | Acknowledges an open escalation                |
| `send_reply`             | Sends a message to a customer on their channel |
| `pause_agent`            | Pauses the agent across every channel          |
| `resume_agent`           | Resumes it                                     |

A tool whose policy requires approval is advertised as such at connection time, so a well-behaved
client can tell the user before it tries.

## Prompts

Three ready-made workflows appear as slash commands in clients that support MCP prompts:

* **Morning triage**, which walks the client through what needs attention
* **Explain this agent reply**, which pulls the retrieval and routing behind one answer
* **Draft knowledge from gaps**, which turns your ranked [knowledge gaps](/agent/knowledge) into
  draft answers

## Errors

Tool errors say what was wrong and what to try, with a correctly shaped example where that helps,
rather than returning a stack trace for the model to guess at.

## Limits and observability

Every call is rate limited per key and recorded. You can see MCP activity, error rates and which
keys are busiest under **Quality, then Assistant**. Keys can carry call budgets. See
[Governance](/assistants/governance).