# MCP server overview

> The Omni Octo MCP server at /mcp — send_sms, place_call and four tools that find and run everything a workspace can do — and how you connect, signing in with your account or with an API key for scripts.

[MCP](https://modelcontextprotocol.io) (Model Context Protocol) is an open
standard for connecting AI clients — Claude Code, Claude Desktop, Codex,
Cursor and other MCP-native hosts — directly to a server's tools, without going
through a chat-style API. Omni Octo has **one** MCP server for your workspace,
at `https://api.omniocto.com/mcp`, over Streamable HTTP.

## How you connect

Sign in with your Omni Octo account. In Claude Code it is one command:

```bash
claude mcp add --transport http omniocto https://api.omniocto.com/mcp
```

Start Claude Code and your browser opens (or type `/mcp` and choose
**Authenticate**): choose a workspace, click **Allow**, and the server is
connected with your role in that workspace. Codex, other clients and what the
sign-in page shows: [Connect](/mcp/connect/#connect-with-one-command).

In the **Claude app** (desktop or claude.ai), add Omni Octo as a custom
connector with the same address and sign in from there. The step-by-step
guide, with screenshots and the tool permissions we recommend: [Connect
Claude](/mcp/claude/).

In the **ChatGPT desktop app's Codex**, add it under **Settings → Plugins →
MCPs** as a Streamable HTTP server and click **Authenticate**: [Connect
ChatGPT and Codex](/mcp/codex/).

For scripts, CI and clients that cannot sign in, send a workspace API key in
the `Authorization: Bearer` header instead ([Get an API
key](/getting-started/api-keys/)).

## What the server offers

Your client sees six tools. Two do the most common jobs by name; the other
four reach everything a workspace can do: messages and calls, campaigns, contacts and lists, the inbox, AI
agents and their knowledge, phone numbers, workflows, billing, and these docs.

| Tool | What it does |
|---|---|
| `send_sms` | Send an SMS from one of the workspace's numbers. It asks for the user's OK first, like `send_message`. |
| `place_call` | Place an AI phone call from one of the workspace's numbers, also after the user's OK. |
| `find_tools` | Search by what you want to do ("text a contact", "pause a campaign", "docs on webhooks"). Returns the best matches with a one-line summary and their risk. |
| `describe_tool` | One tool's full description, risk, how it is approved, and input JSON Schema. |
| `run_tool` | Run a tool with its arguments. |
| `confirm_action` | Approve or cancel a risky call by its id and code, for apps without approval forms. |

Six tools instead of hundreds keeps your client's context small: the whole
list is a few thousand tokens, where listing every tool cost tens of thousands.
Your agent searches when it needs something, the way it would look up a
command.

What it can reach:

- **[API tools](/mcp/api-tools/)**: the public Platform API (`/v1`) as tools.
  Send texts and WhatsApp templates, place AI-agent calls, work the inbox,
  keep contacts and contact lists, run campaigns, follow events.
- **[Octo's tools](/mcp/tools/)**: the same tools the dashboard's Octo uses
  (agents, knowledge, segments, phone numbers, workflows, billing and more),
  including **bulk tools** that act on many matching rows in one approved call.
  Where a name is both, `/mcp` runs the API tool.
- **The docs**: `search_docs` and `get_doc` read this site, so your agent can
  look up how something works without a second server.

Every tool is filtered by the role of the person who signed in, or of the
key's owner, the same way `/v1` does (see
[Authentication](/getting-started/authentication/)).

## Risky actions wait for a person

Calls that spend money, message many people, delete, or change something live
**wait for a person**. In an app that shows approval forms (MCP elicitation, for
example Claude Code), the person sees what will happen and approves or declines
there, and `run_tool` returns the outcome; the model cannot answer that form.

In an app without forms, `describe_tool`'s `approval` says how the tool is
confirmed:

- **Octo's tools:** `run_tool` returns `confirmation_required` with a summary,
  an `action_id` and a `code`; call `confirm_action` only after the person's
  latest message approves that exact action. The ask and its outcome appear in
  an "MCP tools" conversation in the dashboard (one per app per day).
- **API tools:** the first call does nothing and answers "Needs the user's
  OK" with exactly what it would do (a normal result, not an error, with the
  details under `structuredContent.confirmation`, `code: confirmation_required`).
  After the person approves, call `run_tool` again with the same arguments plus
  `confirm: true` and the suggested `idempotency_key`. When the agent already
  showed those exact details and the person's latest message approved them, it
  does not ask twice.

See also [Confirmations](/openai-api/confirmations/).

## Authentication

| | `/mcp` |
|---|---|
| Sign in (OAuth) | yes |
| Workspace API key | yes |

**Sign in** when a person is at the keyboard: the client opens a browser, you
choose a workspace and click **Allow**. Owners and admins see and revoke every
signed-in app under **Settings → Connected apps**, with an activity log;
members see their own. What clients need to support, token lifetimes and
signing in again: [Connect](/mcp/connect/#oauth-clients).

**Use a key** for scripts, CI and clients that cannot sign in. A key in the
`Authorization: Bearer` header keeps working as before and never opens a
browser. See [Connect](/mcp/connect/) for client config, and [Get an API
key](/getting-started/api-keys/) to mint one.

## Older URLs

> **Changed (2026-10-31):** Omni Octo had three MCP servers. They are one now,
> at `/mcp`.

Older addresses keep working, so an existing client config keeps connecting:

- `/mcp/api` and `/mcp/tools` are the same server as `/mcp` (what changed for
  an app already signed in: [Connect](/mcp/connect/#server-url)).
- `/mcp/delegate` (also `/mcp/octo` and, with an API key only,
  `/mcp-meta-agent`) still answers: it hands a request to Octo in plain
  language (`send_message`, `list_conversations`, `get_conversation`). New
  setups should use `/mcp`.

Separately, `https://api.omniocto.com/mcp-docs` is a public docs search that
needs no account (see [Resources for agents](/agents/resources/)).