MCP | PostNuvia | Documentation

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 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)

Open Settings, then Connectors, and click Add custom connector.
Set the name to PostNuvia.
Set the URL to https://mcp.postnuvia.com/mcp.
Click Add, then Connect on the new connector.
A browser window opens at console.postnuvia.com. Sign in.
If you belong to multiple organizations, pick one on the consent screen.
Back in Claude, send a test message like List my PostNuvia inboxes to confirm the connection.

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)

Open Settings, then Security and login, and turn on Developer mode. On a workspace plan, an admin must allow developer mode first.
Open ChatGPT Plugins and click + to add a server.
Set the name to PostNuvia and the URL to https://mcp.postnuvia.com/mcp, and choose OAuth.
Sign in at console.postnuvia.com when the browser window opens. If you belong to multiple organizations, pick one on the consent screen.
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)

Generate an API key at console.postnuvia.com under Settings, then API Keys.
Open Cursor settings, go to MCP, and add a server with this config:

{
  "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 instead and pass POSTNUVIA_API_KEY through the subprocess environment.

Claude Code

Add the server with the claude mcp command:

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 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 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 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 , 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.

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 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 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 to manage API keys and organizations.
Support for help with installation or auth issues.
for the hosted server, compatibility bridges, and generated contract.