# Connect any MCP client

> Connect Claude Code, Codex or another MCP client to the Omni Octo MCP server at /mcp by signing in with your Omni Octo account, or with a workspace API key for scripts and CI.

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](/openai-api/overview/). Use this
  for scripts, CI, a remote machine with no browser, and clients that cannot
  sign in. See [Get an API key](/getting-started/api-keys/) 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](/mcp/api-tools/) (send a text, place a call,
run a campaign), [Octo's tools](/mcp/tools/) (agents, knowledge, phone
numbers, workflows, billing) and the docs search. What each is and how risky
calls are approved: [MCP server overview](/mcp/overview/). To run AI-call
campaigns with it: [Call campaigns from Claude Code or Codex](/mcp/claude-code-campaigns/).

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:

```bash
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](#what-you-see-when-you-sign-in), type `/mcp`, choose the server and
choose **Authenticate**.

**Codex**, signing in:

```bash
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:

```bash
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.

## What you see when you sign in

1. 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.
2. 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.
3. If you belong to more than one workspace, choose one. The app acts as you in
   that workspace, with your role there.
4. 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:

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

With a key, add the header:

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

<a id="oauth-clients"></a>

## Sign-in for client authors (OAuth)

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](#signing-in-again).
- With a key: the `Authorization: Bearer` header carries a valid, non-revoked
  key (see [Get an API key](/getting-started/api-keys/)).
- The URL is `https://api.omniocto.com/mcp`. A `404` means the path has a typo.