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:

An API key (x-api-key)
A workspace identifier: either x-workspace-slug or x-workspace-id

{
  "x-api-key": "your-api-key-here",
  "x-workspace-id": "your-workspace-id-here"
}

You can send Authorization: Bearer <api-key> 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):

{
  "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:

{
  "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.

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 <api-key>. 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.

API Documentation

Conversations

Jobs

Customers

Tickets

Overview

Authenticate

Connect

Cursor

Claude

Stdio-only clients

Tools

Tickets

Ticket messages and dispositions

Conversations

Customers and jobs

Workspace resources

Skills

Tools

Assists

Limits

FAQ

Should I use MCP or REST?

Why is a dashboard action missing?

Do I need both `x-api-key` and `Authorization`?

Why did a tool return unauthorized?

​Overview

​Authenticate

​Connect

​Cursor

​Claude

​Stdio-only clients

​Tools

​Tickets

​Ticket messages and dispositions

​Conversations

​Customers and jobs

​Workspace resources

​Skills

​Tools

​Assists

​Limits

​FAQ

​Should I use MCP or REST?

​Why is a dashboard action missing?

​Do I need both x-api-key and Authorization?

​Why did a tool return unauthorized?

Overview

Authenticate

Connect

Cursor

Claude

Stdio-only clients

Tools

Tickets

Ticket messages and dispositions

Conversations

Customers and jobs

Workspace resources

Skills

Tools

Assists

Limits

FAQ

Should I use MCP or REST?

Why is a dashboard action missing?

Do I need both `x-api-key` and `Authorization`?

Why did a tool return unauthorized?