Connect any MCP client

There are two ways to connect an MCP client to Omni Octo:

Sign in with your Omni Octo account. Claude Code, Codex and other clients that support MCP’s OAuth sign-in open a browser, you choose a workspace and click Allow, and the client is connected. There is no key to copy, store or rotate. Use this when a person is at the keyboard.
A workspace API key in the Authorization: Bearer header, the same key you’d use for the OpenAI-compatible API. Use this for scripts, CI, a remote machine with no browser, and clients that cannot sign in. See Get an API key if you don’t have one yet.

Either way the client gets the same tools. A signed-in app may do what your role allows in the workspace you chose, the same way a key is limited by its owner’s role.

Server URL

Server	Name to give it	URL	How you connect
Omni Octo	`omniocto`	`https://api.omniocto.com/mcp`	sign in, or a key

There is one server. Your agent sees send_sms and place_call, plus four tools, find_tools, describe_tool, run_tool and confirm_action, that reach everything else: the API tools (send a text, place a call, run a campaign), Octo’s tools (agents, knowledge, phone numbers, workflows, billing) and the docs search. What each is and how risky calls are approved: MCP server overview. To run AI-call campaigns with it: Call campaigns from Claude Code or Codex.

Older URLs keep working: https://api.omniocto.com/mcp/api and https://api.omniocto.com/mcp/tools are the same server as /mcp, and https://api.omniocto.com/mcp/delegate (alias /mcp/octo) still answers for existing setups that hand requests to Octo in plain language. Any other path under /mcp/ answers 404.

Changed (2026-10-31): the API tools (/mcp) and the tool catalog (/mcp/tools) are one server now, at /mcp. A config that points at either URL keeps working. An app that signed in through /mcp/tools before 2026-10-31 is asked to sign in again once. The delegate is no longer suggested for new setups.

Connect with one command

Claude Code, signing in:

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

Start Claude Code. If your browser does not open by itself to sign in, type /mcp, choose the server and choose Authenticate.

Codex, signing in:

codex mcp add omniocto --url https://api.omniocto.com/mcp
codex mcp login omniocto

codex mcp login opens your browser. On a machine without one, add --no-browser: Codex prints the sign-in link, and you paste back the address your browser lands on afterwards.

With a key instead (scripts, CI, a remote machine), put it in an environment variable and pass it as a header:

export OMNI_OCTO_API_KEY=sk-octo_...   # Settings → API Keys & Webhooks
claude mcp add --transport http omniocto https://api.omniocto.com/mcp \
  --header "Authorization: Bearer $OMNI_OCTO_API_KEY"
codex mcp add omniocto --url https://api.omniocto.com/mcp \
  --bearer-token-env-var OMNI_OCTO_API_KEY

A server added with a key never opens a browser.

Your browser opens on agent.omniocto.com. If you are not signed in to the dashboard, sign in (or create an account) first; you come back to the same page afterwards.
The page says which app wants to connect (the name is supplied by the app itself), which server it is connecting to (“Omni Octo (omniocto)”), and where it returns: “an app on this computer” for Claude Code and Codex. If it names a website instead, continue only if you started the sign-in from that site.
If you belong to more than one workspace, choose one. The app acts as you in that workspace, with your role there.
Click Allow. The page says you can close the tab, and the client shows the server as connected. Cancel sends the app back with nothing.

Each sign-in connects the server to one workspace. To work in another workspace, sign in again and choose it, or add the server a second time under another name. The page asks every time: an app you approved before still needs your click.

Example client config

Most MCP clients accept a JSON config block naming the server, its URL, and headers. The exact file/format varies by client, but the shape is the same everywhere. A client that can sign in needs only the URL:

{
  "mcpServers": {
    "omniocto": {
      "url": "https://api.omniocto.com/mcp"
    }
  }
}

With a key, add the header:

{
  "mcpServers": {
    "omniocto": {
      "url": "https://api.omniocto.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-octo_..."
      }
    }
  }
}

Sign-in is MCP’s standard authorization, OAuth 2.1 with discovery, so a client needs no Omni Octo-specific setup. /mcp supports it, and so do its aliases /mcp/api and /mcp/tools.

Discovery. A request with no Authorization header answers 401 with WWW-Authenticate: Bearer resource_metadata="…", scope="mcp". The protected-resource metadata (RFC 9728) is at https://api.omniocto.com/.well-known/oauth-protected-resource/mcp; …/oauth-protected-resource with no path is the same document. The aliases have their own documents, …/oauth-protected-resource/mcp/api and …/oauth-protected-resource/mcp/tools, whose resource is the alias URL itself. The authorization server metadata (RFC 8414) is at https://api.omniocto.com/.well-known/oauth-authorization-server, and the same document at /.well-known/openid-configuration.
Registration. Dynamic client registration (RFC 7591) at POST https://api.omniocto.com/oauth/register, for public clients (token_endpoint_auth_method: "none"). A redirect URI is https:, a loopback http://127.0.0.1, http://localhost or http://[::1] on any port, or an app’s private-use scheme. There is no client secret and no pre-registration.
Authorization. The authorization code flow with PKCE: S256 is required, plain is refused. The one scope is mcp. The redirect back to the client carries iss.
Resource indicators (RFC 8707). Send resource with the URL you connected to: https://api.omniocto.com/mcp, or an alias (…/mcp/api, …/mcp/tools). Any of them gives a token for the one server, valid on all three URLs. With no resource, the token is for /mcp. A sign-in made through /mcp/tools before 2026-10-31 no longer works; sign in again.
Tokens. An access token (omniocto_at_…) lasts 1 hour. A refresh token (omniocto_rt_…) lasts 90 days and is replaced on every refresh, so a client used at least once every 90 days never has to sign in again. A replaced refresh token presented again more than 30 seconds after it was replaced signs the app out, because that is what a stolen token looks like (a quick retry of a refresh whose answer was lost is allowed; it gets a new pair, and the refresh token the first attempt received stops working without signing the app out). This check holds for 7 days after the token was replaced; after that the old token is simply unknown. POST https://api.omniocto.com/oauth/revoke (RFC 7009) ends a connection from the client’s side.

The tokens work only on the MCP server. /v1, the platform API and /mcp-meta-agent refuse them; use a key there.

Keys keep working

A key presented in the Authorization header is checked as it always was and never starts a sign-in. A wrong or revoked key answers 401 invalid_api_key, with no WWW-Authenticate header, so the client shows an error rather than opening a browser: fix the key, or remove the header to sign in instead.

Signing in again

A client has to sign in again when its connection was revoked, when it went unused for 90 days, or when you were removed from the workspace (being added back does not bring old connections back). The server then answers 401 with error="invalid_token", and a client that supports sign-in starts it again:

Claude Code: /mcp, choose the server, then Authenticate. To switch workspace, choose Clear authentication first.
Codex: codex mcp login omniocto. To switch workspace, codex mcp logout omniocto first.

Revoking a connection

Settings → Connected apps in the dashboard lists every app signed in to the workspace: the app, the server, who connected it, when, and when it was last used. Revoke signs it out at once: its next request is refused, and it can come back only if someone signs in and approves it again. Below the list, an activity log shows each sign-in, refresh and revocation, with the IP address, for 90 days.

Owners and admins see and revoke every connection in the workspace; other members see and revoke their own. Removing a server from your client (claude mcp remove, codex mcp logout) deletes the tokens on your computer; revoke it in Connected apps to end it on Omni Octo’s side too.

Seeing what a connection did

Each app in Settings → Connected apps, and each key on the API keys page, shows how many tool calls it made in the last 7 days. Recent calls opens the list: the tool (the one run_tool ran, by its own name), the server (omniocto), the status and the time, newest first, kept for 30 days. Who can see it follows the same rule as revoking: owners and admins see every app and key, other members their own.

The results show where they always do, with the app or key named: a message sent through omniocto reads “Sent through the API by Claude Code” (or “by key CI bot”) in Conversations. A key that was deleted, or a connection that is gone, leaves the plain “Sent with the API” label.

Verifying the connection

Once connected, ask your MCP client to list available tools. You should see four: find_tools, describe_tool, run_tool and confirm_action. Ask “who am I connected as?” and the client finds and runs get_me; ask for your numbers and it runs list_senders; ask “how do I set up webhooks?” and it searches the docs.

If the connection is rejected, double-check:

Signed in: the connection is still listed under Settings → Connected apps, and you are still a member of the workspace. If not, sign in again.
With a key: the Authorization: Bearer header carries a valid, non-revoked key (see Get an API key).
The URL is https://api.omniocto.com/mcp. A 404 means the path has a typo.