Connect an MCP client

Every Tinbox deployment exposes a Model Context Protocol endpoint at /mcp. An MCP client (the Claude app, Claude Code, or any agent) connects to it and gets the exact same tools the in-app assistant runs — search mail, summarize threads, draft and send, manage audiences and campaigns. The tool reference documents each one.

This is the focused MCP reference. For the full walk-through — the in-app assistant, MCP, and the CLI side by side — see Connect Claude and agents.

MCP works even when no in-app AI key is configured: the MCP server and the chat assistant are independent, so you can connect Claude to a deployment that has no chat assistant of its own. In the app, everything below is one page: Settings → Integrations.

Connect the Claude app (one-click OAuth)

Open Settings → Integrations in your Tinbox deployment and copy the MCP URL (https://<your-app-host>/mcp). The endpoint supports OAuth 2.1 + PKCE + dynamic client registration, so the Claude app's Add custom connector flow connects with a single consent screen — no token to paste. Leave Client ID / Client Secret blank; Tinbox registers the client automatically.

Connect Claude Code (bearer token)

Claude Code authenticates with a scoped, inbox-bound bearer token. Mint one (it's shown once), then add the server:

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

claude mcp add -t http tinbox https://<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. Prefer the smallest scope that does the job.

What the allowlist narrows

An MCP client sees the manifest twice-gated: a tool appears only if the deployment's app/agent.config.ts allows it (the git-owned ceiling, mirrored by the runtime toggle in Settings → Assistant) and the token's role permits it. Read-only tools run freely; destructive ones (sending) are flagged so the client asks for confirmation. The exact tools an agent currently gets are listed live on Settings → Integrations.

Try it once connected

The setup and send-readiness tools ride along automatically, so a connected agent answers onboarding questions straight away:

• "What's left to set up on this deployment?" → runs get_setup_state over MCP.
• "Can I send a campaign right now?" → runs get_send_readiness.
• "What params does send_email take?" → answered from this reference via the bundled, read-only search_docs tool.

From there: "Import this list of contacts…" and "Draft a campaign to my newsletter audience…" — the same tools, gated by the same authorize() checks that gate a human.