# 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: Getting Started - Reading time: 7 min read - Last updated: 2026-07-13 - Related keywords: MCP Server, MCP Server developer docs, Getting Started, Getting Started 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. 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. Start with read-only or low-risk tools, such as workspace capabilities and subscriber listing. 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. Require explicit approval in the agent platform before the agent can use send, delete, or automation-changing tools. - Preferred transport: Streamable HTTP. - Authentication: OAuth for Claude Desktop and other user-connected clients; `Authorization: Bearer ` for code-first clients. - Tool names are stable, snake_case wrappers around public API operations, such as `subscribers_list`, `broadcasts_create`, and `webhook_subscriptions_create`. - Limit the tools exposed to an agent whenever the platform supports tool limits. A narrow toolset is easier to understand and safer to approve. ## OpenAI Responses API OpenAI's MCP tool integration can connect directly to Mailrith's remote MCP server. This lets your agent use Mailrith through named tools instead of building REST calls itself. Use `allowed_tools` to control which tools the agent can call. For example, a reporting workflow might allow subscriber and broadcast read tools. A campaign drafting workflow might also allow broadcast creation, but sending should still require approval. 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: ["subscribers_list", "broadcasts_create"], require_approval: "never", }, ], }); ``` ## 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, and approve the Mailrith permissions required by the MCP tools. 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, creating sequences requires a sequence write scope, and workflows that inspect templates need template read access. **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": { "subscribers_list": { "enabled": true }, "broadcasts_create": { "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: subscribers_list, broadcasts_create, broadcasts_send_test ``` ## 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.