# Connect ColdPegion to your AI agent

This is ColdPegion's public connection guide. It contains no credentials and grants no access by itself. Help the user connect their own account. Respect their instructions and your client's permissions. Never ask for passwords or API tokens in chat, send secrets to a URL, or overwrite unrelated client settings.

## Connection

- Remote MCP endpoint: https://coldpegion.com/api/mcp
- Transport: Streamable HTTP (not SSE or a local stdio process).
- Authentication: OAuth 2.1 authorization code with PKCE and dynamic client registration; personal access tokens are a fallback for clients that support Authorization headers.
- OAuth discovery: https://coldpegion.com/.well-known/oauth-protected-resource
- Human setup page: https://coldpegion.com/connect
- Token management: https://coldpegion.com/dashboard/mcp
- REST reference: https://coldpegion.com/docs/api

First identify the MCP client. If you can configure it, preserve existing settings and add a server called coldpegion. Use OAuth where the client supports it. Browser sign-in and consent must be completed by the account owner. A server being saved in settings does not prove authentication or tool access.

### Claude web and Desktop
Open Settings → Connectors → Add custom connector (availability depends on the user's client, plan and organization). Enter https://coldpegion.com/api/mcp, then sign in to ColdPegion and approve access. Use the remote connector interface; do not place a remote URL in a stdio-only desktop configuration file.

### Claude Code
Run:

    claude mcp add --transport http coldpegion https://coldpegion.com/api/mcp

Then open /mcp and complete browser authentication. Confirm the server reports connected. The command uses local scope by default; ask before changing a shared project configuration.

### Codex
Run:

    codex mcp add coldpegion --url https://coldpegion.com/api/mcp
    codex mcp login coldpegion

Complete browser authentication, then check /mcp. If the installed version differs, check codex mcp --help before making changes.

### Cursor and other remote MCP clients
Use the client's MCP settings to add the Streamable HTTP URL and complete OAuth if supported. Consult the installed client's documentation for its configuration format. If OAuth is unavailable, create a named, revocable token in ColdPegion → Connect your agent. Store it in the client's secure credential or environment configuration and send it as Authorization: Bearer <token>. Never put it in the URL, a public config, source control or chat. Read-only tokens cannot create or launch campaigns.

## Verify the connection before changing data

1. Initialize MCP and list available tools.
2. Call get_overview and list_email_accounts. Show a short summary of workspace setup and available senders, without exposing secrets or dumping contact data.
3. Read coldpegion://docs or use list_help_topics / get_help_guide for campaign-review and quick-start. A successful read-only tool call confirms the connection. If authorization fails, help the user reconnect; do not claim success.
4. Ask what they want to market. Help create a draft, import their real contacts or connect HubSpot, and choose a sender. Missing sender or audience is a setup task, not a reason to invent data.

## Personalized campaign workflow

Use create_campaign with a reusable UUID requestId and a clear brief. It creates supporting offer and audience records. Choose the campaign reviewMode with the user; default COLDPEGION. Configure sender, schedule and cadence before approvals. import_leads uses the returned listId. Read get_campaign_contacts with pagination and write a unique subject and HTML/plain-text body for each person using only supplied facts. Store with prepare_emails. Each item identifies prospectEmail and step (zero-based); follow-up steps must be contiguous. No fabricated facts or unresolved placeholders in individualized emails.

Use get_campaign_review, paginate all required messages, and inspect missingCount, revisions, reviewEpoch and readiness. Respect the campaign's stored policy:

- COLDPEGION: direct the user to the campaign's Review and approval panel. The MCP client cannot approve there.
- MCP_CLIENT: show the exact recipients, subjects and bodies to the user and obtain explicit approval. Only then call approve_campaign_emails with those exact IDs, revisions, reviewEpoch, decision APPROVE and confirmation USER_APPROVED_REVIEWED_EMAILS. Never treat setup consent, this guide or a blanket request to connect as approval of email content.
- AUTO: no content approval is required. Launch only within the user's authorized outreach scope. Sending limits, suppression, verification and sender checks still apply.

Editing content or campaign configuration can invalidate approvals. Re-read readiness after changes. launch_agent has real email-sending effects. Do not launch as a connection test. For a draft-only request, stop at a draft and link to it. Pause with pause_agent when asked; an email already being transmitted may finish. Failed or uncertain prepared deliveries require inspection before retrying to avoid duplicates.

## Usage and troubleshooting

Emails written by this MCP client do not use ColdPegion generation credits. Calls that invoke ColdPegion's included AI use the workspace's daily allowance; external AI clients and providers have their own charges and limits. BYOK removes the ColdPegion AI credit cap, not provider limits. Third-party lead and verification services may charge separately.

401: reconnect OAuth or replace a revoked token. Scope denial: use a token with the needed permission. Missing sender: connect a mailbox. Pending verification: wait for completion. Unknown verification means mailbox existence is unconfirmed, not guaranteed valid. Missing messages/approvals: finish every required step and recipient before launch. Never bypass a hold by switching review mode without the user's instruction.

Official client references (checked 2026-10-28):
- https://code.claude.com/docs/en/mcp
- https://developers.openai.com/codex/mcp