# Connect through MCP

Canonical: https://suzo.app/docs/mcp-setup

Start with the prompt from **Add agent → Copy setup prompt** in Suzo. Pair in the exact agent session you want to use. The complete, current instructions are also served as [the raw agent guide](https://api.suzo.app/setup/agent).

## Connection map

Your existing agent keeps its context, tools, and permissions. It exchanges MCP calls and events with Suzo; Suzo carries the internet call to your iPhone.

<figure class="docs-flow" role="img" aria-label="Your existing agent exchanges MCP calls and events with the Suzo service, which carries the internet call to your iPhone. Context, tools, and permissions stay with the original agent.">
<div class="docs-flow-node"><strong>Existing agent</strong><span>Context · tools · permissions</span></div>
<div class="docs-flow-edge"><span>MCP</span><b aria-hidden="true">↔</b></div>
<div class="docs-flow-node docs-flow-node-suzo"><img src="/site-assets/suzo.png" width="30" height="30" alt=""/><strong>Suzo service</strong><span>Call events</span></div>
<div class="docs-flow-edge"><span>Internet call</span><b aria-hidden="true">↔</b></div>
<div class="docs-flow-node"><strong>Your iPhone</strong><span>Voice · native panels</span></div>
</figure>

## Pair the agent

The hosted service origin is `https://api.suzo.app`. Use the exact base URL and expiring code supplied by the phone; self-hosted installations use their own trusted origin. Read `GET /v1/harnesses` and select your real harness’s canonical ID. A model name is not a harness ID.

```http
POST /v1/pair/agent
Host: api.suzo.app
Content-Type: application/json

{"code":"<one-time code>","runtime":"codex"}
```

The response includes the contact ID and a scoped agent token. Store that token privately using the harness’s secret store or an owner-only file. Do not print it in logs, put it in command arguments, or commit it. Never use the phone credential or request provider keys from the human.

An unlisted harness can use `other` and an optional `runtimeName` of at most 30 characters. Known harness IDs must not supply `runtimeName`. Reuse an existing connection instead of pairing again when possible.

## Add a Streamable HTTP server

The following is a server entry, not a universal enclosing configuration file:

```json
{
  "url": "https://api.suzo.app/mcp",
  "headers": {
    "Authorization": "Bearer <scoped-agent-token>"
  }
}
```

Use the installed harness’s native MCP configuration. Preserve unrelated servers and use secret environment references where supported. Give each person’s connection a distinct name, for example `suzo_alice`.

Codex users can inspect `codex mcp add --help`; Hermes users can inspect `hermes mcp --help`. Apply the configuration to the profile and session actually running the conversation.

## Verify the running session

Run MCP `initialize` and `tools/list`. Expect all nine tools:

| Tool | Purpose |
| --- | --- |
| `call_user` | Start or join a call using a request UUID |
| `next_call_event` | Read spoken turns, UI actions, and call state |
| `reply_to_call` | Reply to the latest user turn |
| `end_call` | End your call |
| `acknowledge_call` | Record that you processed the call outcome |
| `search_calls` | Search your ended calls on this connection |
| `get_call_transcript` | Read a saved transcript in pages |
| `set_appearance` | Update your contact’s appearance when requested |
| `show_call_ui` | Publish native in-call information and controls |

Writing configuration does not prove this session loaded it. A separate MCP probe proves connectivity, not tool availability in the current chat. Reload only the affected client when needed, and state any remaining step precisely.

## Offer the optional features

After MCP is verified, assess [harness capabilities](https://suzo.app/docs/harnesses). Explain incoming calling and local speech, then wait for the human’s choice before configuring them. Declining either option leaves basic agent-initiated calling connected.

Do not place a test call just to verify setup. Wait for a request to call.