Connect AI Agents with the Migma MCP Server

​

Where this lives in Migma

​

Choose connection type

​

Remote MCP

​

Tool profiles

​

Recommended: OAuth connector setup

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 permits test/direct sends. campaign:write permits campaign creation, send, and schedule. Migma marks both as delivery access.
4. Approve the connection. Migma gives the client a scoped API key automatically, so there is no key to copy or paste.

​

Claim-code fallback

​

CI and server automation

{
  "mcpServers": {
    "migma": {
      "url": "https://migma.ai/mcp",
      "headers": {
        "Authorization": "Bearer your_migma_api_key"
      }
    }
  }
}

​

Local MCP

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

export MIGMA_PROJECT_ID=proj_abc123

claude mcp add --scope user migma -- npx -y @migma/mcp
claude mcp list
claude mcp get migma
claude mcp remove migma

​

Client setup

Cursor

Add Migma MCP to Cursor.

Claude

Connect Claude.ai, Claude Code, or Claude Desktop. Visual setup: Claude tutorial.

ChatGPT

Use the public Migma plugin. Visual setup: ChatGPT tutorial.

Grok

Ask Grok Bot to add Migma Remote MCP, or connect Grok web and Grok Build directly.

Copilot

Connect GitHub Copilot to Migma MCP.

Codex CLI

Add Migma MCP to Codex CLI.

Windsurf

Connect Migma MCP to Windsurf.

Antigravity

Add Migma MCP to Google Antigravity.

Raycast

Use Migma MCP from Raycast AI.

VS Code

Connect Migma MCP to VS Code.

​

Verify the connection

​

Common workflows

​

Design emails (show drafts first)

1. Reuse the working brand and supplied brief or reference. List brands and choose projectId only when needed; ask only for missing required details. Audience and sending-domain setup are not needed for drafts.
2. For researched work, build an exact source-backed fact checklist. Pass required facts in the prompt and up to five public HTTPS source-image URLs through structured images; prompt-only URLs are not image inputs.
3. Create or design with one migma_generate_email call (load that tool by exact name). For several emails pass count (max 12) and name each email’s job in the prompt. Do not call generate once per email. Then poll migma_get_generation_status. Existing HTML or .eml uses migma_import_html instead of generate.
4. Show returned preview images and each canvas link immediately.
5. After first show, verify every required fact and source image before claiming success. If a preview cannot be attached, show its canvas link and say visual verification is incomplete.
6. After the first preview, handle requested edits, inbox checks, or campaign setup. Do not run validate or edit tools before that first show. Text-only edit cannot add structured source images; that requires replacement generation.
7. Run migma_validate_* when the user asks for checks, or as a last step before send.

​

Edit an email

1. Call migma_edit_email once with the target emailId and prompt. Keep the same idempotency_key if the start result is uncertain.
2. Poll the read-only migma_get_email_edit_status tool with emailId, editId, and optional includeHtml.
3. Use that tool’s exact job status. Do not use conversation generation status to decide that the edit finished; a previous conversation turn may already be completed.
4. Never resubmit an edit while it is pending or processing. On failure, inspect the stored email before starting another edit because changes may have been saved.
5. When the status is completed, show the returned preview.

​

Convert existing HTML

1. List brands and choose projectId.
2. Call migma_import_html once with the HTML or .eml source (or htmls for several files). Optional instruction: keep it as-is, or apply the brand.
3. Poll migma_get_generation_status, then show preview images and each canvas link.
4. Each result is one canvas slot with its own emailId. Edit, send, and export use that id.

​

Save brand facts

• Call migma_add_knowledge_base when the user shares lasting facts (tone, products, offers, policies). Do not list first.

​

Favorite an email for future designs

{ "emailId": "<chosen emailId>" }

​

Import a CSV audience

• Call migma_create_contact_import once with the full CSV text and an optional list tag.
• Leave column mapping empty when headers look like email, first name, or last name.
• Prefer this over converting CSV rows into a JSON bulk import.
• The import can wait and return final counts in the same turn.

​

Import from Klaviyo, Mailchimp, or HubSpot

• Call migma_list_provider_import_sources with the brand and provider to list audiences, lists, segments, and tags.
• Call migma_import_contacts_from_provider with one to 25 sources and an optional consentMode (subscribed-only by default).
• The tool can wait up to 45 seconds, then poll migma_get_contact_import for final counts, tag and segment IDs, and non_sendable contacts.

​

Export unsubscribers and reconcile a connected store

1. Choose the brand, then call migma_create_contact_export with filters: {status: "unsubscribed"} and a stable idempotency_key. Optional saved segment and grouped filters narrow the audience. This requires audience:read.
2. Poll migma_get_contact_export with the returned jobId and projectId. Only completed includes a private CSV download URL and actual exported count. Queued work is not a finished export; failure is not an empty audience.
3. The URL expires in one hour. Poll the same job for a fresh URL while it is retained, up to seven days. Retrying creation with the same key and body finds the same job.
4. To inspect a connected store or CRM, use migma_list_connected_tools, then migma_get_connected_tool for the exact argument schema. Discovery requires email:read; execution requires project:write.
5. Obtain approval for the concrete external changes before migma_call_connected_tool. Existing enabled-tool grants and approval settings remain enforced. A tool requiring interactive dashboard approval remains blocked here; review its permissions in the brand’s MCP Servers settings.

​

Out of credits

• On an out-of-credits error, call migma_get_credits and explain the limit briefly. Existing drafts and tasks that use no credits can continue.
• In the general profile or local MCP, use migma_get_upgrade_link when the user asks to manage billing or accepts a relevant billing offer. New subscribers choose a plan before receiving a checkout link. Existing subscribers omit plan to review changes in the billing portal.
• Passing plan for an existing subscription can change it and charge a prorated payment immediately. Obtain explicit approval for that charge first.
• Show the returned URL once and check updated credits before resuming blocked work. A link alone does not confirm payment. This tool is absent from the OpenAI profile.

​

Buy a domain

1. Search availability and yearly prices with migma_search_buyable_domains.
2. Call migma_buy_domain and show the returned checkout URL. The user pays in the browser. A free account can hold one purchased domain; account eligibility and current annual pricing are checked before checkout. The domain purchase renews annually.
3. Poll migma_get_domain_purchases until the domain is active.
4. Set it up for sending with migma_setup_domain. When DNS is still required, migma_setup_domain and migma_verify_domain return a connectUrl that opens one-click DNS setup in Migma.

​

Send or schedule

1. Open the link and sign in. You see the email and the same details.
2. Click Send or Schedule, or Decline. Edit in Migma opens the campaign or email if you want to change it first.

​

Other

• Open the email in Migma from the returned canvas link
• Fetch exact emailId values
• Send a test email
• Create a campaign draft
• Export approved email to HTML, PNG, PDF, Klaviyo, Mailchimp, or HubSpot
• Read campaign metrics and logs
• Manage contacts, lists, segments, and sending domains
• Check the plan and remaining credits (migma_get_credits); subscription management (migma_get_upgrade_link) is available in the general profile or local MCP
• Track existing domains (migma_get_domain_purchases); domain search and checkout (migma_search_buyable_domains, migma_buy_domain) are available in the general profile or local MCP, with payment in the user’s browser
• Manage DNS records on domains bought in Migma (migma_list_dns_records, migma_add_dns_record, migma_remove_dns_record): add A, AAAA, CNAME, MX, TXT, or NS records like Google Workspace MX or a site-verification TXT, and remove user-added records. Migma’s email sending records are protected, and the root and www names are reserved for domain forwarding

​

Security

• Prefer OAuth connection for clients that support it.
• Use scoped API keys.
• Review scopes before approval. email:send allows test/direct sends. campaign:write allows campaign creation, send, and schedule. Only allow either when you trust the connector to deliver mail.
• Revoke OAuth-created and manually created keys from Settings → Developers → API Keys.
• Keep human approval enabled before sends, exports, audience changes, and campaign changes.
• Send API keys through the documented authorization header.
• Treat MCP like direct API access. Tool calls use the same Migma permissions as SDK, CLI, and REST API requests.

​

Troubleshooting

​

Resources