# MCP Server



> Mailrith's official MCP server is the highest-level interface for agent runtimes. This page covers the remote endpoint plus copy-paste examples for OpenAI, Claude, n8n, and Pipedream.



- Human page: https://mailrith.com/developers/mcp

- Category: Getting Started

- Reading time: 7 min read



## What this guide covers

Connect Mailrith to agent runtimes through the official remote MCP server and streamable HTTP transport.



## Official MCP Server

Mailrith exposes an official remote MCP endpoint for agent runtimes that work better with tools than raw HTTP calls. The MCP server maps the public API into 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 an agent platform supports MCP directly. Use the REST API or SDKs when you need a conventional backend integration, strict custom retry behavior, or full control over request construction.

1. Choose OAuth for user-connected runtimes such as Claude Desktop, or create a workspace API key for server-side runtimes that can safely store bearer credentials.
2. Decide which Mailrith tools you will allow the agent to use. Keep this list narrow.
3. Configure the agent runtime with `https://api.mailrith.com/mcp`. If the runtime supports custom authorization headers, use `Authorization: Bearer <workspace_api_key_or_oauth_token>`.
4. Start with read-only or low-risk tools such as workspace capabilities and subscriber listing.
5. Test the workflow with a small prompt and verify the actions in Mailrith.
6. Add write tools only after the read flow is reliable.
7. Keep send, delete, and automation-changing tools behind explicit approval in the agent platform.

- Preferred transport: Streamable HTTP.
- Authentication: OAuth for Claude Desktop and other user-connected clients; `Authorization: Bearer <workspace_api_key_or_oauth_token>` 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 allows it. A narrow toolset is easier to reason about 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 constructing REST calls itself.

Use `allowed_tools` to keep the agent focused. For example, a reporting workflow might allow subscriber and broadcast read tools, while a campaign drafting workflow might also allow broadcast creation but still require approval before sending.

Keep the Mailrith API key in a server-side secret and pass it 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 path, 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`, 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 needed by the MCP tools.

On the Mailrith approval screen, review the requested permissions before approving. Mailrith grants the permissions that the connected app requests, so configure the connector or client to ask only for the scopes its workflow needs.

Configure the connector with only the tools the Claude workflow needs. Do not give write or send tools to read-only workflows.

When troubleshooting permission errors, remove and re-add stale failed connectors, then confirm the connector requested the needed permissions. 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 expose MCP connection fields in a UI rather than a code-first SDK. Mailrith's remote server fits those clients directly with a streamable HTTP URL and a Bearer token.

Use environment variables or the platform's secret manager for the Mailrith key. Avoid pasting 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 behaves correctly.

**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 once 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 drives 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 it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.