> ## Documentation Index > Fetch the complete documentation index at: https://docs.tranthor.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP server reference > The Tranthor MCP server: its address, how it signs people in, the access it asks for, and every tool it offers. Tranthor runs one remote [Model Context Protocol](https://modelcontextprotocol.io) server. Claude, ChatGPT and other MCP clients use it to work in a Tranthor workspace. To connect as a person, follow [Connect Claude or ChatGPT](https://docs.tranthor.com/guide/connect-claude.md). This page is the reference for developers. > [!NOTE] > > The server returns text and structured data only. It has no app screens or embedded views. ## Server | | | | - | - | | **Address** | `https://api.tranthor.com/mcp` | | **Transport** | Streamable HTTP, stateless | | **Sign-in** | OAuth 2.0 with PKCE | | **Works in** | The one workspace the person chose when connecting | Every call acts as the person who connected, within their role (see [Roles](#roles)). Nothing a tool takes from the conversation can change the workspace it works in. ## Sign-in A request without a valid token gets `401` and a `WWW-Authenticate: Bearer resource_metadata="..."` header that points at the protected resource metadata. | Document | Address | | - | - | | Protected resource metadata | `https://api.tranthor.com/.well-known/oauth-protected-resource/mcp` | | Authorization server metadata | `https://api.tranthor.com/.well-known/oauth-authorization-server` | * **Client registration.** Client ID Metadata Documents (CIMD) are preferred. Dynamic client registration (RFC 7591) is the fallback, at the `registration_endpoint` in the authorization server metadata. * **PKCE.** Every authorization uses `S256`. * **Resource.** Send `resource=https://api.tranthor.com/mcp` with the authorization request. Access tokens are bound to that resource. A token without it, or one issued for a different resource, is refused with `401`. * **Refresh.** Ask for the `offline_access` scope to receive a refresh token, so the person stays connected without signing in again. ### Scopes | Scope | Lets the assistant | | - | - | | `tranthor:read` | Read segments, journeys, broadcasts, message templates, results and analytics. | | `tranthor:write` | Save drafts, hand Tranthor a brief, pause and resume journeys, and ask the Supervisor. | | `tranthor:send` | Send a broadcast or start a journey, after two confirmations. | | `offline_access` | Stay connected without signing in again. | The person chooses what to allow on the consent screen. A scope is a ceiling, not a grant: each call also re-checks the connection, the person's membership and their role. ## Roles | Role | Tools | | - | - | | Viewer | Read tools only. | | Author | Read tools, the draft tools, `start_brief`, `ask_supervisor`. | | Workspace manager, Admin | Everything an Author has, plus `pause_journey`, `resume_journey` and the send tools. | A tool the connection can't use is not listed, so a Viewer's assistant never sees the draft tools. ## Tools Every tool has a `title` and annotations. Read tools set `readOnlyHint: true`. Every other tool sets `destructiveHint: true`, so a client can ask before it runs. All tool names are 27 characters or fewer. ### Read tools Need `tranthor:read`. Open to every role. | Tool | What it does | | - | - | | `list_segments`, `get_segment` | Lists saved segments, and returns one segment with its size. | | `list_journeys`, `get_journey` | Lists journeys with their status, and returns one journey's entries, completions and customers still in it. | | `list_broadcasts`, `get_broadcast` | Lists broadcasts, and returns one broadcast's status, segment, template and delivery results. | | `list_message_templates`, `get_message_template` | Lists message templates, and returns one template. | | `get_workspace_results` | Returns the last 30 days of revenue, orders and messages, the numbers on Home. | | `get_analytics_catalog`, `query_analytics` | Lists what can be measured, and returns totals and breakdowns over time. Never returns a row about one customer. | | `list_needs_you` | Lists what is waiting for a person, most important first. Nothing in it can be approved from here. | | `search`, `fetch` | Finds items in the workspace by text, and returns one by id. | | `get_brief_status` | Returns how a brief is going and links the drafts it saved. Offered to roles that can write. | | `get_supervisor_reply` | Returns the Supervisor's answer to an `ask_supervisor` call. Offered to roles that can write. | Rates are fractions from 0 to 1 in most tools. In `query_analytics`, campaign open, click and conversion rates are percentages from 0 to 100. ### Tools that save or change work Need `tranthor:write`. | Tool | Minimum role | What it does | | - | - | - | | `save_segment_draft` | Author | Saves a draft segment. | | `save_journey_draft` | Author | Saves a draft journey. | | `save_broadcast_draft` | Author | Saves a draft broadcast. | | `save_message_template_draft` | Author | Saves a draft message template. | | `start_brief` | Author | Hands Tranthor a brief to build from. It returns at once, and it saves drafts only. | | `ask_supervisor` | Author | Starts or continues a conversation with the Supervisor. What it would change comes back as a confirm card that the person approves in Tranthor. | | `pause_journey` | Workspace manager | Pauses a running journey. | | `resume_journey` | Workspace manager | Resumes a paused journey. This sends again to customers already in it. | A draft does nothing until someone sends, starts or publishes it. No tool publishes, approves or deletes. ### Tools that send Need `tranthor:send`, which the person ticks separately when connecting. Minimum role: Workspace manager. | Tool | What it does | | - | - | | `preview_broadcast_send` | Returns Tranthor's preview of sending a draft broadcast: the customers it reaches, the sender and the risks. | | `send_broadcast` | Sends the broadcast that was previewed, after the person approves the preview and types its number of customers. | | `preview_journey_start` | Returns the preview of starting a journey that has never run. | | `start_journey` | Starts the journey that was previewed, after the person's two confirmations. | A send follows the preview it was bound to. A preview is good for one send and expires after a short time, so a send that follows a changed message or audience needs a new preview. A send that reaches the whole audience, more customers than the person has approved before, or a new channel or sender is **Critical**: it is approved inside Tranthor only, and the tools answer with a link instead. ## Endpoint for Google Gemini and Google Search use a separate, fixed endpoint, `https://api.tranthor.com/mcp/google/v1`, because Google freezes a published app's tools. It has its own OAuth resource, and a token for one endpoint is refused on the other. It offers 16 tools: the read tools for segments, journeys, broadcasts, message templates, results, analytics and Needs you, plus the four draft tools. It never sends, starts, pauses or approves anything, and its tokens never carry `tranthor:send`. A change to its tools goes on a new version of the endpoint, and the old one stays up until Google retires it. ## Errors Tools return a message that says what to fix: an unknown id, a role that does not allow the tool, a send that needs a new preview, or an item that is not in the connected workspace. A malformed id is rejected before any lookup. ## Activity and revoking Every write is recorded in the connection's activity log, and items it creates are marked with who made them and through which assistant. The person can see the log and revoke the connection in Settings, **AI Agents**. Revoking ends access at once. ## Related * [Connect Claude or ChatGPT](https://docs.tranthor.com/guide/connect-claude.md): the guide for people using the connection. * [AI Agents](https://docs.tranthor.com/guide/ai-agents.md): where Tranthor's own agents live and how you stay in control. * [Contact controls](https://docs.tranthor.com/guide/contact-controls.md): the limits every agent send must respect. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.