> ## 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 a Vorel workspace over the Model Context Protocol: endpoints, auth, tools and limits.

Vorel exposes a workspace over the Model Context Protocol, so an MCP-compatible client can query and
act on it directly.

This page is the developer contract. For what your team can do with it day to day, see
[Team assistants: MCP](/assistants/mcp).

## Endpoints

```
https://app.vorel.ai/api/mcp           # read tools, plus write tools when the key allows
https://app.vorel.ai/api/mcp/readonly  # read tools only
```

Both are streamable HTTP MCP servers.

The read-only endpoint does not refuse write calls at runtime. The write tools are structurally
absent from the server it builds, so the guarantee does not depend on a scope check or a flag being
set correctly.

## Authentication

### API key

Issue a key with the `assistant:read` scope. Send it as a bearer token.

```
Authorization: Bearer vapk_live_...
```

Add `assistant:write` to allow the write tools. See
[Authentication](/api-reference/authentication).

### OAuth

Where your client supports it, connect over OAuth instead. Scopes map one to one onto the key
scopes:

| OAuth scope             | Key scope         |
| ----------------------- | ----------------- |
| `vorel:assistant.read`  | `assistant:read`  |
| `vorel:assistant.write` | `assistant:write` |

OAuth carries a person, so write actions are attributed to that user rather than to a shared key.
Prefer it when more than one human uses the same client.

Protected-resource metadata is served at `/api/well-known/oauth-protected-resource`.

<Warning>
  A key with `assistant:write` lets whatever client holds it pause the agent and message real
  customers, with no human between the model's decision and the action. Some MCP clients share
  connector credentials across an organisation. Check your client's sharing model before issuing a
  write key, and consider requiring [approvals](/assistants/governance).
</Warning>

## Tools

### Read

| Tool                          | Returns                                                                   |
| ----------------------------- | ------------------------------------------------------------------------- |
| `search_tenant_records`       | Conversations, customers, leads, appointments                             |
| `get_conversation_transcript` | One conversation's full transcript                                        |
| `search_knowledge`            | Matching knowledge entries                                                |
| `query_analytics`             | Metrics over a window                                                     |
| `get_tenant_overview`         | Current workspace state                                                   |
| `whoami`                      | Workspace, scopes, endpoint variant, rate limits in force                 |
| `list_capabilities`           | Live channels, business hours, and what this connection can and cannot do |
| `search_vorel_docs`           | These docs, for answering product questions with citations                |
| `ask_vorel`                   | One collected answer to a natural-language question                       |
| `send_vorel_mcp_feedback`     | Writes an audit row with your feedback. Touches no tenant data            |

The list and search tools take:

* `response_format`: `concise` (default) or `detailed`. Concise costs roughly a third of the tokens.
* `max_results`: a cap. Where results are trimmed, the response says so and states how to narrow the
  query rather than truncating silently.

`ask_vorel` takes `{ question, conversation_id? }` and runs a full turn server-side, returning
written prose. It is the only read tool that costs a model call on our side, and it is rate limited
separately.

### Write

Registered only when the credential carries `assistant:write` and write actions are enabled:

| 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 is set to require approval is advertised with a `vorel/requiresApproval` marker
at `tools/list`, so a client can warn the user before calling it. The marker is advertising, not
enforcement. Enforcement happens on the call.

## Prompts

Three parameterized prompts surface as slash commands in clients that support them: morning triage,
explain this agent reply, and draft knowledge from gaps.

## Errors

Tool errors return specific, actionable text: what was wrong, what to try, and a correctly shaped
example where that helps. They are written for a model to recover from rather than for a human to
debug.

## Limits

Per-key rate limits apply, with a separate, tighter limit on `ask_vorel` and on the write tools.
`whoami` reports the limits currently in force.

Every call is recorded and attributed to the key or the user. Keys can carry monthly call budgets.
See [Assistant governance](/assistants/governance).