> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect MCP-compatible agents to Migma with Remote MCP or Local MCP.

Migma MCP lets agents work with your Migma brands from an editor or agent client. Agents can prepare emails, fetch email IDs, validate output, create campaign drafts, send tests, export approved emails, manage contacts, and inspect results.

<Info>
  Remote MCP is available at `https://migma.ai/mcp` over Streamable HTTP. Use OAuth connection when your client supports it, or use a bearer API key manually.
</Info>

## Where this lives in Migma

Open **My Brands**, choose a brand, then open **Tools**. The app `/mcp` route redirects to the active brand's Tools page.

Create API keys from **Settings → Developers → API Keys**.

## Choose connection type

| Type       | Use when                                       | Config                      |
| ---------- | ---------------------------------------------- | --------------------------- |
| Remote MCP | Client supports hosted MCP                     | `url: https://migma.ai/mcp` |
| Local MCP  | Client only supports command-based MCP servers | `npx -y @migma/mcp`         |

## Remote MCP

### Recommended: OAuth connector setup

Use this path for clients that support OAuth connection, such as claude.ai custom connectors.

1. Add Migma as a custom connector with `https://migma.ai/mcp`.
2. Follow the client sign-in flow. It opens Migma so you can review and approve access.
3. On `migma.ai/connect/authorize`, check the app name, return host, and requested scopes. `email:send` means the connector can send emails from your account.
4. Approve the connection. Migma gives the client a scoped API key automatically, so there is no key to copy or paste.

OAuth-created keys appear in **Settings → Developers → API Keys** and can be revoked there.

### Manual API key setup

Use this path when your client does not support OAuth connection or asks you to paste a bearer token.

```json theme={null}
{
  "mcpServers": {
    "migma": {
      "url": "https://migma.ai/mcp",
      "headers": {
        "Authorization": "Bearer your_migma_api_key"
      }
    }
  }
}
```

Some clients ask for the bearer token separately. Use the same Migma API key. Do not put API keys in URLs.

## Local MCP

Local MCP is available with `npx -y @migma/mcp`.

```json theme={null}
{
  "mcpServers": {
    "migma": {
      "command": "npx",
      "args": ["-y", "@migma/mcp"],
      "env": {
        "MIGMA_API_KEY": "your_migma_api_key"
      }
    }
  }
}
```

Optional environment variable:

```bash theme={null}
export MIGMA_PROJECT_ID=proj_abc123
```

Use `MIGMA_PROJECT_ID` only for Local MCP when one brand is the default. Remote MCP clients should call `migma_list_projects` and pass `projectId`.

Remote MCP clients do not use `MIGMA_PROJECT_ID`. Call `migma_list_projects`, then pass `projectId`.

For Claude CLI, add the local server with:

```bash theme={null}
claude mcp add --scope user migma -- npx -y @migma/mcp
claude mcp list
claude mcp get migma
claude mcp remove migma
```

## Client setup

<CardGroup cols={2}>
  <Card title="Cursor" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/cursor.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=1bc8ebb9727a9e7b6671d0c5a7dae482" href="/agents/mcp-cursor" width="120" height="120" data-path="images/logos/cursor.png">
    Add Migma MCP to Cursor.
  </Card>

  <Card title="Claude" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/claude-code.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=21dc5dcc66f09660a16fbea3297333b4" href="/agents/mcp-claude" width="120" height="120" data-path="images/logos/claude-code.png">
    Connect Claude Desktop or Claude Code.
  </Card>

  <Card title="ChatGPT" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/chatgpt.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=f88137fa5b3adadac975427b68304728" href="/agents/mcp-chatgpt" width="120" height="120" data-path="images/logos/chatgpt.png">
    Add Migma as a custom ChatGPT MCP connector.
  </Card>

  <Card title="Copilot" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/copilot.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=a1ae89d7f530a9604e469be973f465d4" href="/agents/mcp-copilot" width="120" height="120" data-path="images/logos/copilot.png">
    Connect GitHub Copilot to Migma MCP.
  </Card>

  <Card title="Codex CLI" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/codex.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=a4b7a9b1b86045262a76ff6dd3067637" href="/agents/mcp-codex" width="120" height="120" data-path="images/logos/codex.png">
    Add Migma MCP to Codex CLI.
  </Card>

  <Card title="Windsurf" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/windsurf.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=ebbece28d09dcab4e8a49b58e80e243c" href="/agents/mcp-windsurf" width="120" height="120" data-path="images/logos/windsurf.png">
    Connect Migma MCP to Windsurf.
  </Card>

  <Card title="Antigravity" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/antigravity.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=db40bf15f23a3195738b84f99c1b2148" href="/agents/mcp-antigravity" width="120" height="120" data-path="images/logos/antigravity.png">
    Add Migma MCP to Google Antigravity.
  </Card>

  <Card title="Raycast" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/raycast.png?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=0517327673bc3a44f7e48532e8fc00f0" href="/agents/mcp-raycast" width="120" height="120" data-path="images/logos/raycast.png">
    Use Migma MCP from Raycast AI.
  </Card>

  <Card title="VS Code" icon="https://mintcdn.com/migmaai/kT6TJgF40rDP8_qB/images/logos/vscode.svg?fit=max&auto=format&n=kT6TJgF40rDP8_qB&q=85&s=a33b2611b16ff0ff7f6a02f6d54c07b8" href="/agents/mcp-vscode" width="100" height="100" data-path="images/logos/vscode.svg">
    Connect Migma MCP to VS Code.
  </Card>
</CardGroup>

## First tool call

Ask your client to call:

```text theme={null}
migma_get_capabilities
```

It returns available tools, write/read behavior, idempotency rules, brand scoping, and guided workflows. Agents should call it before choosing tools.

## Common workflows

* List brands and choose `projectId`
* Prepare one email or a multi-email series
* Fetch exact `emailId` values
* Validate compatibility, links, spelling, and deliverability
* Send a test email
* Create a campaign draft
* Export approved email to HTML, MJML, Klaviyo, Mailchimp, HubSpot, or PDF
* Read campaign metrics and logs
* Manage contacts, lists, segments, and sending domains

## Security

* Prefer OAuth connection for clients that support it.
* Use scoped API keys.
* Review scopes before approval. `email:send` allows test and live sends.
* Revoke OAuth-created and manually created keys from **Settings → Developers → API Keys**.
* Keep human approval enabled before sends, exports, audience changes, and campaign changes.
* Never place API keys in query parameters.
* Treat MCP like direct API access. Tool calls use the same Migma permissions as SDK, CLI, and REST API requests.

## Troubleshooting

| Symptom                     | Fix                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| OAuth consent does not open | Use the manual API key path, or use Local MCP if your client cannot complete connector approval.                |
| `Missing Bearer token`      | Finish the OAuth connector flow, or add `Authorization: Bearer <MIGMA_API_KEY>` for manual Remote MCP requests. |
| Client cannot send headers  | Use Local MCP with `npx -y @migma/mcp`.                                                                         |
| `projectId is required`     | Call `migma_list_projects`, then pass `projectId`.                                                              |
| Tool list looks stale       | Restart the client or reset cached MCP tools.                                                                   |

## Resources

<CardGroup cols={2}>
  <Card title="npm Package" icon="cube" href="https://www.npmjs.com/package/@migma/mcp">
    Local MCP package.
  </Card>

  <Card title="Agent Registration" icon="key" href="/agent-registration">
    Let agents request scoped access.
  </Card>
</CardGroup>