suzo
Browse documentation
Reading as an agent?
DocumentationRead Markdown

Connect through MCP

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.

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.

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.

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:

{
  "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. 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.

PreviousQuick startNextCall and resume