MCP Server

The Orbitali MCP server is a Model Context Protocol server that lets coding agents (Claude Code, Cursor, Windsurf, and other MCP clients) configure voice agents through the public API. It wraps /public/v1 with higher-level, workflow-safe tools so the agent can create or reuse agents, create, update, or delete tools, and mint realtime sessions without hand-writing REST calls. It can also manage the knowledge documents that power native search_knowledge retrieval, assign phone numbers to agents, and inspect call history and agent runtime logs.

You can connect to it in two ways:

• Remote — a hosted Streamable HTTP endpoint at https://mcp.orbitali.ai/mcp. Nothing to install; each request is authorized with the API key your MCP client sends.
• Local — the @orbitali/mcp npm package running over stdio, launched by your MCP client with bunx.

Both expose the same tools. Use the remote server unless your MCP client cannot send HTTP headers, you need to point at a staging or self-hosted API, or you want to upload knowledge documents from local files.

When to use it

Use the MCP server when you want a coding agent to configure Orbitali from your app repository. For example, you can ask the agent to add a webhook route to your app, create or reuse the matching Orbitali voice agent, and register the webhook or HTTP tools that route exposes.

For direct backend integrations, keep using the public REST API reference. MCP is an agent-facing adapter over that API, not a replacement for it.

Create an API key

Create an API key in the Orbitali dashboard under Settings → API keys. Keep this key server-side and only pass it to your MCP client configuration.

Connect to the remote server

The hosted server lives at https://mcp.orbitali.ai/mcp and speaks Streamable HTTP. Pass your API key on every request as a bearer token:

Authorization: Bearer sk_your_key

The hosted MCP process does not store your API key. Each request is authorized with the key supplied by your MCP client.

Claude Code

claude mcp add --transport http orbitali https://mcp.orbitali.ai/mcp \
  --header "Authorization: Bearer sk_your_key"

Cursor / Windsurf / generic remote MCP clients

{
  "mcpServers": {
    "orbitali": {
      "url": "https://mcp.orbitali.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_key"
      }
    }
  }
}

Run the server locally

The local server runs over stdio and is launched by your MCP client. It reads ORBITALI_API_KEY (required) and ORBITALI_API_BASE_URL (defaults to https://api.orbitali.ai) from the environment.

Claude Code

claude mcp add orbitali \
  --env ORBITALI_API_KEY=sk_your_key \
  -- bunx @orbitali/mcp

For staging or self-hosted environments, also pass ORBITALI_API_BASE_URL:

claude mcp add orbitali \
  --env ORBITALI_API_KEY=sk_your_key \
  --env ORBITALI_API_BASE_URL=https://api.orbitali.ai \
  -- bunx @orbitali/mcp

Cursor / Windsurf / generic MCP clients

{
  "mcpServers": {
    "orbitali": {
      "command": "bunx",
      "args": ["@orbitali/mcp"],
      "env": {
        "ORBITALI_API_KEY": "sk_your_key",
        "ORBITALI_API_BASE_URL": "https://api.orbitali.ai"
      }
    }
  }
}

Tools

• list_agents — list the agents in your organization.
• list_agent_tools — list an agent's custom tools.
• list_mcp_integrations — list connected MCP servers and their cached tool definitions without returning credentials.
• list_agent_mcp_tools — list the connected MCP tools assigned to an agent.
• configure_agent_mcp_tools — replace an agent's connected MCP tool assignments.
• get_or_create_agent — reuse an agent matching name, agentType, language, voiceName, and serverUrl, or create one.
• patch_agent — update agent fields with optimistic concurrency (expectedUpdatedAt).
• ensure_agent_tools — create missing tools by name, optionally updating existing matching tools.
• update_agent_tool — replace one existing custom tool definition.
• delete_agent_tool — delete one custom tool from an agent.
• list_knowledge_documents — list the knowledge documents configured on an agent.
• upload_knowledge_document — upload document text or a local .txt, .md, or .pdf file to an agent's knowledge base.
• delete_knowledge_document — delete a knowledge document from an agent.
• create_realtime_session — mint a short-lived realtime session for an active agent.
• list_phone_numbers — list the organization's phone numbers with claim status and current agent assignment.
• assign_phone_number — assign a claimed phone number to an agent, moving it if it was assigned to another agent.
• unassign_phone_number — remove a phone number assignment from an agent; the number stays claimed.
• list_calls — list recent call history, optionally filtered by agent.
• get_call — get one call with summary, transcript messages, tool invocations, and LLM usage.
• list_agent_logs — list agent runtime logs from the last 24 hours, filterable by severity and session.

upload_knowledge_document accepts either content or filePath, but not both. filePath is read from the machine the server runs on, so it only works with the local stdio server; with the remote server, pass the document text as content. Local file uploads are limited to .txt, .md, or .pdf files up to 1 MB.

End-to-end example

After configuring the MCP server, open your app repository in your coding agent and prompt it with the desired voice-agent behavior:

Use the Orbitali MCP server to create or reuse a webhook voice agent for this app.

Agent:
- name: Acme Support Agent
- type: webhook
- language: en-US
- voice: eve
- server URL: https://acme.example.com/api/orbitali/webhook
- greeting: Thanks for calling Acme. How can I help?

Tools:
- lookup_order: look up an order by order id or customer email
- create_ticket: create a support ticket with caller details and a short summary

Knowledge:
- upload docs/support-policy.md if it is not already in the agent knowledge base

First inspect existing agents and tools. Reuse matching resources and only create missing tools.

The coding agent should then:

• inspect existing Orbitali agents with list_agents;
• call get_or_create_agent with the requested voice, prompt, and server URL;
• inspect existing custom tools with list_agent_tools;
• call ensure_agent_tools with only the tool definitions your app exposes, using updateExisting: true when existing matching tools should be replaced;
• call update_agent_tool or delete_agent_tool when the prompt asks for a specific tool change or removal;
• inspect existing knowledge documents with list_knowledge_documents when the prompt includes knowledge-base content;
• call upload_knowledge_document for missing knowledge documents, or delete_knowledge_document when asked to remove one;
• report the agent ID, whether the agent was created or reused, which tools were created or already existed, and any knowledge documents uploaded or deleted.

Expected result

The configured agent appears in the Orbitali dashboard. If the agent is still a draft, activate it in the dashboard or ask the coding agent to patch it to status: "active" once the webhook endpoint is deployed and reachable over HTTPS.