> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oration.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect Claude, Cursor, or ChatGPT to your Oration workspace over MCP.
The Oration MCP server is the same workspace API as REST, exposed as tools for Claude, Cursor, and ChatGPT. Auth, RBAC, and workspace scoping match `/api/v2`.
MCP is opt-in. Only a curated set of procedures are tools. The rest of the dashboard API is not exposed.
## Overview
MCP (Model Context Protocol) lets a language model call Oration as tools instead of you writing HTTP requests. Each tool maps to a tRPC procedure. Input schemas come from the same Zod schemas as REST.
Use MCP when an assistant should search tickets, trigger conversations, or look up agents in your workspace. Use REST when you are integrating from your own backend.
The server URL is:
```
https://www.oration.ai/api/mcp
```
## Authenticate
Send the same credentials as REST:
1. An API key (`x-api-key`)
2. A workspace identifier: **either** `x-workspace-slug` **or** `x-workspace-id`
```json theme={null}
{
"x-api-key": "your-api-key-here",
"x-workspace-id": "your-workspace-id-here"
}
```
You can send `Authorization: Bearer ` instead of `x-api-key`. Workspace headers are still required.
The API key's workspace role applies. A member who cannot assign tickets over REST cannot assign them over MCP.
## Connect
### Cursor
Add a server in Cursor MCP settings (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
```json theme={null}
{
"mcpServers": {
"oration": {
"url": "https://www.oration.ai/api/mcp",
"headers": {
"x-api-key": "your-api-key-here",
"x-workspace-slug": "your-workspace-slug"
}
}
}
}
```
### Claude
Add a custom connector with URL `https://www.oration.ai/api/mcp` and the same headers.
### Stdio-only clients
If the client cannot speak Streamable HTTP, wrap the URL with [mcp-remote](https://www.npmjs.com/package/mcp-remote):
```json theme={null}
{
"oration": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://www.oration.ai/api/mcp",
"--header",
"x-api-key: your-api-key-here",
"--header",
"x-workspace-slug: your-workspace-slug"
]
}
}
```
## Tools
Tool names are snake\_case. Prefer search tools when you do not have an id; prefer get-by-id when you do.
### Tickets
| Tool | When to use |
| -------------------------------- | ----------------------------------------------------------------------- |
| `tickets_search` | Filter and paginate tickets. Start here if you do not have a ticket id. |
| `tickets_get_by_id` | Fetch one ticket, including type, status, attributes, and disposition. |
| `tickets_create` | Create a ticket. Requires a ticket type id. |
| `tickets_update` | Patch ticket fields. Not for status, assignee, or custom attributes. |
| `tickets_change_status` | Move a ticket to another workflow status. |
| `tickets_assign` | Assign a ticket to a member. Get the user id from `members_list`. |
| `tickets_snooze` | Pause a ticket until a given time. |
| `tickets_upsert_attribute_value` | Set a custom attribute. |
| `tickets_delete` | Permanently delete a ticket. Irreversible. |
### Ticket messages and dispositions
| Tool | When to use |
| ------------------------------------ | ------------------------------------------- |
| `ticket_messages_list` | Read the thread on a ticket. |
| `ticket_messages_create` | Add a message to a ticket. |
| `ticket_dispositions_list` | See codes currently attached to a ticket. |
| `ticket_dispositions_list_available` | See codes you can attach for a ticket type. |
| `ticket_dispositions_attach` | Attach a disposition code. |
| `ticket_dispositions_detach` | Detach a disposition code by linker row id. |
### Conversations
| Tool | When to use |
| ------------------------------------ | ------------------------------------------------------- |
| `conversations_trigger` | Start one or more AI conversations. Requires `agentId`. |
| `conversations_search` | Filter and paginate conversations. |
| `conversations_get_by_id` | Fetch one conversation by id. |
| `transcripts_get_by_conversation_id` | Fetch the transcript for a conversation. |
| `post_call_analysis_create` | Create a post-call analysis for a conversation. |
### Customers and jobs
| Tool | When to use |
| ------------------------------- | ----------------------------------------------- |
| `customers_search` | Filter and paginate customers. |
| `customers_get_by_id` | Fetch one customer by UUID. |
| `customers_get_by_phone_number` | Fetch one customer by phone number. |
| `customers_create_batch` | Create or upsert many customers. |
| `jobs_get_by_id` | Poll a background job returned by another tool. |
### Workspace resources
| Tool | When to use |
| --------------------------- | ------------------------------------------------------------------- |
| `agents_list` | List AI agents. Use the id as `agentId` on `conversations_trigger`. |
| `agents_get_by_id` | Fetch one agent config. |
| `campaigns_list` | List outbound campaigns. |
| `campaigns_get_by_id` | Fetch one campaign. |
| `campaigns_get_stats` | Fetch campaign performance. |
| `queues_list` | List routing queues. |
| `queues_get_by_id` | Fetch one queue. |
| `knowledge_bases_list` | List knowledge bases. |
| `knowledge_bases_get_by_id` | Fetch one knowledge base. |
| `phones_list` | List provisioned phone numbers. |
| `teams_list` | List teams. |
| `teams_get_by_id` | Fetch one team. |
| `members_list` | List members. Use the user id with `tickets_assign`. |
| `webhooks_list` | List webhook endpoints. |
### Skills
Skills are reusable capabilities. Packs group them. Attach a pack to an agent to make those skills available on calls.
| Tool | When to use |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `skills_list` | List workspace skills. Optionally filter by `skillPackId`. |
| `skills_get_by_id` | Fetch one skill, including template and pack membership. |
| `skills_create` | Create a custom skill. Prefer `skills_install_from_template` when a catalog template fits. |
| `skills_update` | Edit a skill. Reset a templated skill with `skills_reset_to_default`. |
| `skills_delete` | Permanently delete a skill. Irreversible. |
| `skills_clone` | Copy a skill to edit without changing the original. |
| `skills_toggle_in_pack` | Add or remove a skill from a pack. |
| `skills_reset_to_default` | Restore a templated skill to the catalog default. |
| `skills_install_from_template` | Install one catalog skill. Needs `skillTemplateId` and `skillPackTemplateId`. |
| `skills_install_all_from_pack_template` | Install every skill in a pack template. |
| `skills_export` | Export skills as CSV. |
| `skills_preview_import` | Preview a CSV import without writing. |
| `skills_apply_import` | Apply a previewed CSV import. |
| `skills_field_mapping_ai` | Suggest CSV column mappings before preview. |
| `skill_packs_list` | List skill packs. |
| `skill_packs_get_by_id` | Fetch one skill pack. |
| `skill_packs_create` | Create an empty pack. Add skills with `skills_toggle_in_pack`. |
| `skill_packs_update` | Rename or describe a pack. |
| `skill_packs_delete` | Delete a pack. Skills in it are not deleted. |
| `skill_packs_clone` | Copy a pack. |
| `skill_templates_list` | List catalog skill templates. |
| `skill_templates_get_by_id` | Fetch one catalog skill template. |
| `skill_pack_templates_list` | List catalog pack templates. |
| `skill_pack_templates_get_by_id` | Fetch one catalog pack template. |
| `agents_add_skill_packs` | Attach packs to an agent. |
| `agents_remove_skill_pack` | Detach a pack from an agent. |
### Tools
A tool is an HTTP integration. Actions are the individual requests on that tool.
| Tool | When to use |
| ------------------------ | ---------------------------------------------------------------- |
| `tools_list` | List tools. Fetch one (with its actions) with `tools_get_by_id`. |
| `tools_get_by_id` | Fetch one tool and its actions. |
| `tools_create` | Create a tool. Add actions with `tool_actions_create`. |
| `tools_update` | Edit tool metadata. Change actions with `tool_actions_update`. |
| `tools_delete` | Permanently delete a tool and its actions. Irreversible. |
| `tools_clone` | Copy a tool including its actions. |
| `tool_actions_get_by_id` | Fetch one tool action. |
| `tool_actions_create` | Create HTTP actions on a tool. |
| `tool_actions_update` | Edit a tool action. |
| `tool_actions_delete` | Permanently delete a tool action. Irreversible. |
| `tool_actions_clone` | Copy a tool action. |
| `tool_actions_from_curl` | Draft an action from a curl command. Does not save. |
| `tool_actions_test` | Execute a tool action against its endpoint as a test. |
### Assists
An assist is a human-in-the-loop workflow. Actions are the steps on that assist.
| Tool | When to use |
| ----------------------------- | -------------------------------------------------------------------- |
| `assists_list` | List assists. Fetch one (with its actions) with `assists_get_by_id`. |
| `assists_get_by_id` | Fetch one assist and its actions. |
| `assists_create` | Create an assist. Add steps with `assist_actions_create`. |
| `assists_update` | Edit assist metadata. Change steps with `assist_actions_update`. |
| `assists_delete` | Permanently delete an assist and its actions. Irreversible. |
| `assists_list_by_group` | List assists in one assist group. |
| `assists_get_unique_values` | Get distinct filter values before listing. |
| `assists_list_user_completed` | List assists the API-key user has completed. |
| `assists_get_stats` | Get assist stats. |
| `assist_actions_get_by_id` | Fetch one assist action. |
| `assist_actions_create` | Create steps on an assist. |
| `assist_actions_update` | Edit an assist action. |
| `assist_actions_delete` | Permanently delete an assist action. Irreversible. |
| `assist_actions_clone` | Copy an assist action. |
Input fields are defined by each tool's JSON Schema in the MCP client. Do not copy REST path parameters into the tool call unless the schema asks for them.
## Limits
* Tools run as the API key's user in the workspace from the request headers.
* Creating or editing agent graphs, flows, and designer objects is not available over MCP. Skill, tool, tool-action, assist, and assist-action management is.
* OAuth for MCP clients is not supported. Use an API key.
* SSE at `/api/sse` exists for older clients. Prefer Streamable HTTP at `/api/mcp`.
Read more on the [REST API](/api-reference/introduction).
## FAQ
### Should I use MCP or REST?
Use MCP when a model should operate in the workspace. Use REST from your own servers and automations. They share auth and permissions.
### Why is a dashboard action missing?
MCP is a curated surface. If the tool is not in the tables above, call REST or do the action in the product.
### Do I need both `x-api-key` and `Authorization`?
No. Send `x-api-key`, or send `Authorization: Bearer `. Always send a workspace header.
### Why did a tool return unauthorized?
The API key is missing, disabled, expired, or the user lacks the permission for that procedure. Check the key and the member's role.