# MCP Server > Mailrith's official MCP server is the highest-level interface for agent runtimes. This page covers the remote endpoint and includes copy-paste examples for OpenAI, Claude, n8n, and Pipedream. - Human page: https://mailrith.com/developers/mcp - Markdown page: https://mailrith.com/developers/mcp.md - Category: AI Agent Platform - Reading time: 7 min read - Last updated: 2026-07-22 - Related keywords: MCP Server, MCP Server developer docs, AI Agent Platform, AI Agent Platform developer docs, Mailrith developer docs, Mailrith public API, Official MCP Server, OpenAI Responses API, Claude MCP Connector, n8n and Pipedream, Agents, SDKs, API Reference ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Connect Mailrith to agent runtimes through the official remote MCP server and streamable HTTP transport. ## Official MCP Server Mailrith provides an official remote MCP endpoint for agent runtimes that work better with tools than with raw HTTP calls. The MCP server exposes the public API as named tools that agents can inspect and call. The remote endpoint is `/mcp` on the API origin. It accepts workspace API keys and OAuth access tokens, so workspace scope and permissions behave the same way as the REST API. Use the MCP server when the agent platform supports MCP directly. Use the REST API or SDKs when you need a standard backend integration, custom retry behavior, or full control over how requests are built. Every client uses the same server URL and sees the same reviewed focused-tool catalog. During OAuth, choose what the connection should do. Mailrith grants the matching permissions and checks them again when each tool runs. 1. Choose OAuth for user-connected runtimes such as Claude Desktop. Create a workspace API key only for server-side runtimes that can safely store bearer credentials. 2. Decide which Mailrith tools the agent is allowed to use. Keep the allowed tool list as small as possible. 3. Configure the agent runtime to use `https://api.mailrith.com/mcp`. If the runtime supports custom authorization headers, set `Authorization: Bearer `. 4. For OAuth, choose the Work Profile that matches the job on Mailrith's approval screen. Start with Reporting when the workflow only needs reads. If a later task needs another resource, reconnect from the agent app and choose the matching Work Profile. 5. Test the workflow with a small prompt. Then check Mailrith and confirm the agent made only the expected actions. 6. Add write tools only after the read flow works reliably. 7. Grant only the resource permissions the connected agent needs. Mailrith checks the resource permission and workspace on every request, without adding a second action-approval step. - Preferred transport: Streamable HTTP. - Authentication: OAuth for Claude Desktop and other user-connected clients; `Authorization: Bearer ` for code-first clients. - The hosted server exposes a fixed reviewed catalog of focused tools such as `subscribers_list`, `broadcasts_create`, `broadcasts_preflight`, and `broadcasts_send`. - Limit the tools exposed to an agent whenever the platform supports tool limits. A narrow toolset is easier to understand and safer to approve. - Every submitted tool includes its exact input and output schema, OAuth permissions, and safety annotations. ## OpenAI Responses API OpenAI's MCP tool integration can connect directly to Mailrith's remote MCP server and use focused tools with exact schemas. Use `allowed_tools` to keep only the focused tools needed for the job. A reporting workflow can keep capability, workspace, and Subscriber reads. A Broadcast preparation workflow can add sender, targeting, Template, draft, and preflight tools without enabling schedule or send. Store the Mailrith API key in a server-side secret, and pass the key as an authorization header in the tool configuration. **Use Mailrith as an MCP Tool Source in OpenAI** ```ts import OpenAI from "openai"; const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, }); const response = await openai.responses.create({ model: "gpt-5.1", input: "List the newest subscribers and draft a re-engagement broadcast.", tools: [ { type: "mcp", server_label: "mailrith", server_url: "https://api.mailrith.com/mcp", headers: { Authorization: `Bearer ${process.env.MAILRITH_API_KEY}`, }, allowed_tools: [ "discovery_get_capabilities", "subscribers_list", "sender_identities_list", "segments_list", "email_templates_list", "broadcasts_create", "broadcasts_preflight", ], require_approval: { always: { read_only: false, }, }, }, ], }); ``` ## Claude MCP Connector Claude Desktop can connect to Mailrith's remote MCP server through Anthropic's custom connector flow. Mailrith uses OAuth for this connection, so users do not paste workspace API keys into Claude Desktop. In Claude Desktop, open Customize > Connectors, add a custom connector named Mailrith, enter `https://api.mailrith.com/mcp`, and then click Connect on the added connector. Claude opens Mailrith in the browser so the user can sign in, choose a workspace, choose what the connection should do, and approve the matching permissions. On the Mailrith approval screen, check the requested permissions before approving. Mailrith grants the permissions requested by the connected app, so configure the connector or client to request only the scopes needed for its workflow. Configure the connector with only the tools needed by the Claude workflow. Do not allow write or send tools for read-only workflows. When troubleshooting permission errors, first remove stale failed connectors, and then add the connector again. After reconnecting, confirm the connector requested the permissions required for the workflow. For example, drafting a Sequence requires `sequences:write`, activating it requires `sequences:write`, and inspecting templates requires `email_templates:read`. **Use Mailrith With Claude's MCP Connector** ```bash curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: mcp-client-2025-11-20" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 1200, "messages": [ { "role": "user", "content": "List the newest subscribers and propose a broadcast." } ], "mcp_servers": [ { "type": "url", "url": "https://api.mailrith.com/mcp", "name": "mailrith", "authorization_token": "MAILRITH_API_KEY_HERE" } ], "tools": [ { "type": "mcp_toolset", "mcp_server_name": "mailrith", "default_config": { "enabled": false }, "configs": { "discovery_get_capabilities": { "enabled": true }, "subscribers_list": { "enabled": true }, "sender_identities_list": { "enabled": true }, "segments_list": { "enabled": true }, "email_templates_list": { "enabled": true }, "broadcasts_create": { "enabled": true }, "broadcasts_preflight": { "enabled": true } } } ] }' ``` ## n8n and Pipedream Workflow platforms usually provide MCP connection fields in a UI instead of a code-first SDK. Mailrith's remote server works with these clients by using a streamable HTTP URL and a Bearer token. Store the Mailrith key in environment variables or in the platform's secret manager. Do not paste the raw key into step names, logs, shared screenshots, or exported workflow files. Start with one low-risk tool, such as listing subscribers or reading workspace capabilities. Add write tools only after you confirm the workflow performs the expected actions. **n8n MCP Client Fields** ```text Transport: Streamable HTTP Server URL: https://api.mailrith.com/mcp Authentication: Header Header name: Authorization Header value: Bearer {{$env.MAILRITH_API_KEY}} ``` **Pipedream Remote MCP Server Fields** ```text Server URL: https://api.mailrith.com/mcp Authorization header: Bearer {{process.env.MAILRITH_API_KEY}} Suggested tools: discovery_get_capabilities, workspace_get, subscribers_list, subscribers_get ``` ## Related Guides - [Agents](https://mailrith.com/developers/agents.md): Mailrith exposes a compact discovery stack for AI agents: llms files on the marketing site, version metadata on the API root, the versioned OpenAPI contract, authenticated capability discovery, and official SDK and MCP entry points after a workspace key is available. - [SDKs](https://mailrith.com/developers/sdks.md): Mailrith ships official TypeScript and Python SDKs generated from the same public contract that powers the OpenAPI document and capability map. - [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.