MCP

Set up the MCP

Connect your AI agent (Claude Code, Codex CLI, or other MCP host) to send emails through Constant Contact for Agents.

What you need to start

Constant Contact for Agents account — Sign up at ctct.dev if you don't have one.
Production sending setup — Required only for full_execution sends. The workspace default sender/domain must be configured and verified for production, or your agent must supply a production-authorized from. Omit from only when that default is ready; otherwise confirm production sending setup before retrying. Test sends (execution_class: test) use the CTCT sandbox domain and do not require your domain.

Security note: OAuth is the recommended authentication method — your agent opens a browser for you to log in securely. If you prefer API key authentication, keep keys out of prompts and source control. Use environment variables or your agent's secret store, and grant only the scopes needed.

Authenticate with your agent

Claude Code

In Claude Code, paste this command:

! claude mcp add ctct --transport http https://mcp.ctct.dev/mcp

Then start a new session, run /mcp, choose "ctct" from the menu, and log in to your account.

Codex CLI

In Codex CLI, paste this command:

! codex mcp add ctct --url https://mcp.ctct.dev/mcp

Then run ! codex mcp login ctct and log in to your account.

Gemini CLI

In Gemini CLI, paste this command:

! gemini mcp add --transport http ctct https://mcp.ctct.dev/mcp

Then run /mcp auth ctct (or choose "ctct" from the menu if prompted) and log in to your account.

ChatGPT

ChatGPT MCP setup requires ChatGPT on the web, Developer mode enabled, and a supported plan or workspace role. Write actions such as send_email are available on Business, Enterprise, and Edu workspaces with Developer mode authorized; consumer accounts may not see Create or allow write-capable tools. Workspace admins may need to enable Developer mode before members can create apps.

Menu labels vary by rollout. Follow OpenAI's Developer mode guidance if your Settings paths differ.

Open Settings (personal) or Workspace settings (Business, Enterprise, or Edu) and go to Apps.
Enable Developer mode. If the toggle is unavailable, ask your workspace admin to allow it.
From the same Apps page, select Create — do not create the server from the chat composer's Apps picker.
Fill in the fields:
- Name: ctct
- Description: Email infrastructure designed for how AI agents work.
- MCP server URL: https://mcp.ctct.dev/mcp
Select the authentication method (OAuth) and complete the login flow when prompted.
Run Scan tools and confirm actions such as send_email appear.
Start a new chat, open the Developer mode tools menu, and enable the ctct app for the conversation.

Authenticate via API key

If you prefer API key authentication over OAuth, store your key as the CTCT_API_KEY environment variable in your agent's configuration (for example, ~/.claude/settings.json for Claude Code). Then restart your agent and run:

I'm using API key authentication. Please:
- Initialize the MCP server at https://mcp.ctct.dev/mcp using my CTCT_API_KEY environment variable
- If you receive a "scope_selection_required" error, show me the available workspaces so I can choose one

Note on API key method: If you prefer API key authentication, securely provide your key to your agent with an environment variable instead of logging in. When initializing the MCP, if the credential can access multiple workspaces, you'll receive a scope_selection_required (409) error with workspace_options — select one and retry with X-Workspace-Id.

Verify your connection

Once setup is complete, ask your agent:

List the available tools and resources for the ctct MCP. What can I do?

You should see tools like send_email, resources like cc://public-mcp/discovery/catalog, and available prompts.

Send a test email

After setup, try a sandbox send first — test mode does not require your domain and the backend supplies the sender when from is omitted:

Send a test email to [your-email] from the ctct MCP using execution_class test. Omit from.

See Examples for production prompts and more ready-to-use copy.

Security notes

Do not expose API keys in browser code or paste them into agent prompts.
Use a different key per environment so local and production agent activity are easy to audit.
Leave trust disabled unless you have reviewed the tools exposed to that agent and the workspace it can access.
Ask the agent to explain planned tool calls before allowing actions that create sends.
Rotate the key if a local config file with a real API key was committed or shared.

Troubleshooting

Problem	Likely cause	Solution
Invalid API key error	Key format wrong or key revoked	Double-check your key starts with `sek_`. Generate a new one in your account if needed.
Domain not verified	DNS records not published for a production sending domain	Go to the Domains page in your account and complete domain verification before `full_execution` sends.
Can't send email	Test vs production mismatch, or production sender not ready	For first sends, use `execution_class: test` and omit `from`. For production, use `full_execution` with `explicit_production_confirmation: true` only when the workspace default sender/domain is configured and verified for production (or supply a production-authorized `from`).
Production send blocked (`sender_profile_unavailable` or `sender_domain_not_verified`)	The workspace default sender/domain is not ready for production, or the supplied `from` is not production-authorized.	Confirm production sending setup with the user before retrying. Omit `from` only when the workspace default sender is ready; otherwise use a different production-authorized `from`.
Tool result has `execution.status: "awaiting_confirmation"`	Production send paused for explicit confirmation. The JSON-RPC result keeps `isError: false` — this is not a failure.	Confirm intent with the user, then retry with `explicit_production_confirmation: true` and a new `idempotency_key` (for example, `production-send-confirmed-002`). Do not reuse the key from the suspended call.
API-key authentication error	The bearer token is missing, revoked, or not available to the agent.	Check that `CTCT_API_KEY` is exported into the process that starts your agent.
Workspace selection error	Your API key can access multiple workspaces and the request did not specify which one to use.	Tell your AI agent: Ask me to choose a workspace, then retry with the selected workspace ID.
Tool result has `isError: true`	The MCP request succeeded, but the business action was rejected or failed.	Tell your AI agent: My last MCP tool call returned an error. Help me understand what went wrong and how to fix it. See Errors & Troubleshooting for response shapes and retry rules.

Required headers

Header	When
`Authorization: Bearer <API_KEY_OR_OAUTH_TOKEN>`	Every MCP request
`X-Workspace-Id: <WORKSPACE_ID>`	When the credential can access multiple workspaces

Built-in discovery resources

URI	What it returns
`cc://public-mcp/discovery/catalog`	The resolved public MCP catalog for the selected workspace and surface.
`cc://public-mcp/discovery/publication`	Publication diagnostics, counts, visibility, and resource payload posture.
`cc://public-mcp/discovery/verification`	Verification checks proving the current public MCP edge behavior.

Next steps

Examples — Agent prompts for sending emails and debugging.
Errors & Troubleshooting — Auth failures, error codes, and interpreting tool results.