Skip to content
Tinbox
Sign in

Connect Claude and agents — chat, MCP, CLI

Put an agent to work on your inbox — the in-app assistant, Claude Desktop or Claude Code over MCP, and the tinbox CLI for headless agents. All three ride one shared, allowlist-scoped tool manifest.

Tinbox is agent-first and human-supervised. The same tools show up in four places — the in-app assistant, external MCP clients, the CLI, and the SDK — because they all stand on one shared tool manifest. An agent gets no special powers: the same authorize() gate that checks a human checks the agent. This guide connects the three you'd use to put an agent on your inbox: the assistant, Claude over MCP, and the CLI for headless agents.

The in-app assistant (nothing to connect)

If you set an AI key during setup (ANTHROPIC_API_KEY or OPENAI_API_KEY), the chat assistant is already live in the app. It runs the same tools — search mail, summarize threads, draft and send, manage audiences and campaigns — and stays behind the same approval gates: read-only tools run freely, irreversible ones (sending, launching) ask you first. Ask it "What's left to set up?" and it answers from the live checklist; ask it to "draft a campaign for…" and it builds one you approve.

MCP works even when no in-app AI key is configured — the assistant and the MCP server are independent. You can connect Claude to a deployment that has no chat assistant of its own.

Connect Claude over MCP

Every deployment exposes a Model Context Protocol endpoint at /mcp. An MCP client connects to it and gets the manifest, narrowed by your org's tool allowlist. The endpoint is read-only-safe by default and includes a bundled search_docs tool, so a connected agent can answer "what params does send_email take?" straight from this reference.

Claude Desktop (one-click OAuth)

The /mcp endpoint supports OAuth 2.1 with PKCE and dynamic client registration, so Claude Desktop's Add integration flow connects with a single consent screen — no token to paste. Copy your deployment's MCP URL from Settings → Integrations (https://<your-app-host>/mcp) and add it there.

Claude Code (bearer token)

Mint a scoped, inbox-bound token, then add the server. The token is shown once:

tinbox tokens create --inbox support --role agent --ttl 30d --json

claude mcp add -t http tinbox https://&#x3C;your-app-host>/mcp \
  --header "Authorization: Bearer tbx_…"

--role sets the ceiling — viewer (read) < agent (read + draft + reply) < admin (+ grants). A read-scoped token can never send, an expired one fails closed on everything. Prefer the smallest scope that does the job.

The CLI for headless agents

For a coding agent operating a deployment without a chat UI, the tinbox CLI is the surface — a thin veneer over the deployment's own tRPC API. Two rules make it predictable to script:

  • --json is a hard contract. With --json, stdout is exactly one JSON document (a success payload or { "error": { "code", "message" } }), no ANSI, all decoration on stderr. JSON.parse(stdout) works unconditionally.
  • Exit codes carry the branch: 0 success · 1 error (incl. a CAS conflict) · 2 auth failure (missing/invalid/expired token) · 3 not found.

Point the CLI at the deployment and confirm the token:

export TINBOX_API_URL=https://&#x3C;your-app-host>
export TINBOX_TOKEN=tbx_…
tinbox whoami --json      # exit 0 + your accessible inboxes; exit 2 = bad/expired token

(tinbox login --api-url … --token … persists the same to ~/.tinbox/config.json, chmod 600.)

From there the core loop is find → read → draft → probe → update → send, all CAS-versioned so two agents (or an agent and a human) can't clobber each other's edits. The send paths are ledgered and idempotent, and nothing sends without human-granted authority. The full contract — every command's flags, the conflict bodies, the review-first outbox PR lane, and what an agent structurally can't do — is in the repo's AGENTS.md and packages/cli/AGENT-USAGE.md.

What the manifest exposes

Browse the whole surface, and how it maps across chat / MCP / CLI / SDK, in the tools reference and its capability matrix. The setup and send-readiness tools ride along automatically, so a connected agent can answer "what's left to set up?" (get_setup_state) and "can I send a campaign right now?" (get_send_readiness) over MCP — the same tools this onboarding uses.

Next steps