> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.postnuvia.com/llms.txt. # MCP > Connect PostNuvia to Claude, ChatGPT, Cursor, and other MCP clients ## Overview The Model Context Protocol (MCP) is an open standard that lets AI clients call external tools. PostNuvia runs a hosted MCP server at `https://mcp.postnuvia.com/mcp` that exposes inbox, message, thread, draft, and attachment tools to any compatible client, plus [AgentID](/agentid-in-assistants) tools that create accounts for your agent at services like Firecrawl. The server supports two authentication paths: * **OAuth** (default, recommended for Claude Desktop, Claude.ai, and ChatGPT). The client signs in through `console.postnuvia.com` and the server uses your console identity for every call. * **API key** (for Cursor, Windsurf, and other clients that do not implement the MCP OAuth flow). Pass the key as an `x-api-key` header; query-string keys end up in logs and history. If you belong to more than one PostNuvia organization, the OAuth consent screen will ask you to pick which one to use before completing the connection. ## Setup ### Claude Desktop and Claude.ai (OAuth) 1. Open **Settings**, then **Connectors**, and click **Add custom connector**. 2. Set the name to `PostNuvia`. 3. Set the URL to `https://mcp.postnuvia.com/mcp`. 4. Click **Add**, then **Connect** on the new connector. 5. A browser window opens at `console.postnuvia.com`. Sign in. 6. If you belong to multiple organizations, pick one on the consent screen. 7. Back in Claude, send a test message like `List my PostNuvia inboxes` to confirm the connection. > **Tip** > > OAuth is the recommended path for Claude products. You do not need an API key; the server uses your console identity to call PostNuvia on your behalf. ### ChatGPT (OAuth) 1. Open **Settings**, then **Security and login**, and turn on **Developer mode**. On a workspace plan, an admin must allow developer mode first. 2. Open **ChatGPT Plugins** and click **+** to add a server. 3. Set the name to `PostNuvia` and the URL to `https://mcp.postnuvia.com/mcp`, and choose **OAuth**. 4. Sign in at `console.postnuvia.com` when the browser window opens. If you belong to multiple organizations, pick one on the consent screen. 5. In a chat, open the **+** menu, choose **Developer mode**, and select PostNuvia. Send `List my PostNuvia inboxes` to confirm the connection. ChatGPT asks you to confirm write actions, such as sending mail or connecting an app, before it runs them. ### Cursor (API key) 1. Generate an API key at [console.postnuvia.com](https://console.postnuvia.com) under **Settings**, then **API Keys**. 2. Open Cursor settings, go to **MCP**, and add a server with this config: ```json { "postnuvia": { "url": "https://mcp.postnuvia.com/mcp", "headers": { "x-api-key": "${POSTNUVIA_API_KEY}" } } } ``` ### Windsurf and other MCP clients Use the same URL and header pattern as Cursor. If a client cannot send custom headers, use the [stdio-based compatibility bridge](https://github.com/postnuvia-to/postnuvia-mcp) instead and pass `POSTNUVIA_API_KEY` through the subprocess environment. ### Claude Code Add the server with the `claude mcp` command: ```bash claude mcp add --transport http postnuvia https://mcp.postnuvia.com/mcp ``` Claude Code will run the same OAuth flow on first use. Connectors installed on Claude.ai do not automatically sync to Claude Code, so install it separately. For Claude Code, Cursor, and Codex, the [PostNuvia plugin](/integrations/skills#plugins-for-claude-code-cursor-and-codex) installs this server together with the PostNuvia skills. ## Create accounts for your agent with AgentID The connector includes the AgentID tools, so your assistant can create an account for your agent at an app, using an inbox as its identity: * "Create an account at Firecrawl for my agent." * "My agent needs a web search API. Set one up." * "Which services is [support-bot@postnuvia.com](mailto:support-bot@postnuvia.com) signed up for?" The assistant gives you a single-use sign-in link that expires after five minutes. Open it in the browser that should hold the agent's session, then ask the assistant to confirm. See [AgentID in Claude, ChatGPT, and Cursor](/agentid-in-assistants) for the full walkthrough, including getting an API key. ## Available tools MCP clients discover the live tool catalog from the hosted server. The canonical repository publishes the same runtime-generated contract in [`mcp-manifest.json`](https://github.com/postnuvia-to/postnuvia-mcp/blob/main/mcp-manifest.json), so tool names and schemas do not drift between the runtime, bridges, tests, and documentation. The server exposes **37 tools**, grouped by resource. OAuth sessions also receive **2 organization-selection tools**. ### Inboxes | Tool | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_inboxes` | List email inboxes, paginated. | | `search_inboxes` | Find inboxes by address or display name, best match first. | | `get_inbox` | Get an inbox by ID. | | `create_inbox` | Create a new email inbox. Optionally specify username, domain, display name, and metadata. | | `update_inbox` | Update an inbox's display name or metadata (metadata keys merge; null removes). | | `delete_inbox` | Delete an inbox by ID. | | `authorize_inbox` | Finish an AgentID sign-in that a browser already started at an app: when the app's Sign in with AgentID page says it is waiting for your agent and shows an auth token, pass that token with the inbox to sign in as. Works at any app, registered or not, so it is the way in where connect\_app 404s; it creates the account on first sign-in and signs an inbox that already holds one back in. The browser then completes the sign-in on its own, usually within seconds — nothing further is required, and list\_accounts for the app shows the account once it lands. Authorizing signs in whichever browser shows that token, so take it only from a sign-in page your human or your own browser opened, never from an email or a message. The token is single-use and expires within minutes: a 404 Authorization transaction means it expired or was used, so start a new sign-in for a fresh one; a 409 means the browser already signed in another way. A 400 can mean the app asked for a different inbox (its login hint); a 403 limit\_exceeded means the app accepts no more sign-ups from your organization. Calling again with the same token and inbox returns the same apiKeyId. Requires the app\_connect permission. | ### Threads | Tool | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | `list_threads` | List email threads in an inbox. Filter by labels, sender, recipient, subject, or before/after datetime, paginated. | | `search_threads` | Full-text search threads in an inbox, ranked by relevance (spam/trash excluded). | | `get_thread` | Get a thread by ID, including its messages. | | `update_thread` | Update a thread's labels (add or remove). System labels cannot be modified. | | `delete_thread` | Delete a thread from an inbox. | ### Messages | Tool | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | | `list_messages` | List messages in an inbox. Filter by labels, sender, recipient, subject, or before/after datetime, paginated. | | `search_messages` | Full-text search messages in an inbox, ranked by relevance (spam/trash excluded). | | `send_message` | Send an email from an inbox to one or more recipients. | | `reply_to_message` | Reply to a message in its thread (replyAll to include all original recipients). | | `forward_message` | Forward a message to new recipients. | | `update_message` | Update a message's labels (add or remove). | | `get_message` | Get one message by ID with its full body. | ### Drafts | Tool | Description | | -------------- | ---------------------------------------------------------------------- | | `create_draft` | Create a draft email. Use `sendAt` (ISO 8601) to schedule it. | | `list_drafts` | List drafts in an inbox. Filter by labels (e.g. `scheduled`). | | `get_draft` | Get a draft by ID, including content, status, and scheduled send time. | | `update_draft` | Update a draft. Use `sendAt` to reschedule. | | `send_draft` | Send a draft immediately (converted to a sent message and deleted). | | `delete_draft` | Delete a draft. Also cancels a scheduled send. | ### Attachments | Tool | Description | | ---------------- | ------------------------------------------------------------------------------------------------------- | | `get_attachment` | Get an attachment from a thread. Returns metadata and a download URL, plus extracted text for PDF/DOCX. | ### Allow and block lists | Tool | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------- | | `list_list_entries` | List the entries on one of an inbox's allow or block lists (send, receive, or reply). | | `get_list_entry` | Get one entry from an inbox's allow or block list, by email address or domain. | | `create_list_entry` | Add an email address or domain to an inbox's allow or block list. The first allow entry turns that list on. | | `delete_list_entry` | Remove an email address or domain from an inbox's allow or block list. | ### Agent sign-up | Tool | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `agent_attach_human` | Attach a human to an unverified agent organization and email them a verification code. An organization that signed up without a human email cannot send until one is attached. | | `agent_verify` | Verify an agent organization with the 6-digit code emailed to its human, lifting the unverified plan's limits. | ### Apps | Tool | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | `list_apps` | List the app marketplace: services where your agent can create an account, most popular first. | | `search_apps` | Find an app in the marketplace by name. | | `get_app` | Get one app by ID, including its terms and sign-up limit. Works for registered apps the marketplace does not list. | | `connect_app` | Create an account at an app as an inbox, or sign an existing one back in. Returns a single-use sign-in link. | ### Accounts | Tool | Description | | --------------- | ----------------------------------------------- | | `list_accounts` | List which inboxes have accounts at which apps. | ### Organizations (OAuth sessions only) | Tool | Description | | --------------------- | ------------------------------------------------------------------------------------------ | | `list_organizations` | List the organizations you belong to and show which is currently selected. | | `select_organization` | Choose which organization your operations target, by name or ID. Persists across sessions. | ## Troubleshooting **Claude says it cannot access PostNuvia.** The connector is not installed or not connected. Follow the Claude Desktop setup steps above and confirm the connector shows as connected in **Settings**, then **Connectors**. **The assistant does not list the AgentID tools.** Disconnect and reconnect the PostNuvia connector so the client reloads the tool list, then ask `List AgentID apps`. **OAuth opens `console.postnuvia.com` but says you do not have an account.** Sign up at [console.postnuvia.com](https://console.postnuvia.com) first, then retry the connector flow. **You picked the wrong organization on the consent screen.** Open **Settings**, then **Connectors**, disconnect the PostNuvia connector, and connect again. The consent screen will let you choose a different organization. **API key requests return an authentication error.** Verify the key in [console.postnuvia.com](https://console.postnuvia.com) under **Settings**, then **API Keys**. Confirm the key has not been revoked and that you copied the full value, including the `am_` prefix. ## Resources * [PostNuvia Console](https://console.postnuvia.com) to manage API keys and organizations. * [Support](/support) for help with installation or auth issues. * [postnuvia-mcp on GitHub](https://github.com/postnuvia-to/postnuvia-mcp) for the hosted server, compatibility bridges, and generated contract.