Connect MCP

Set up and query PostShiba from Cursor with the same API key you use for REST.

PostShiba runs an MCP server over streamable HTTP at https://app.postshiba.com/mcp. Every tool maps to a documented REST endpoint, with the same permissions and send gates, so an assistant can create clusters, add domains, and check delivery for you.

Before you start

You need a Send only, Full access, or Support key. See Create an API key.

Add the server to Cursor

Open your MCP config. Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project.
Add the postshiba server and replace YOUR_API_KEY with your key.
Save. Cursor lists the PostShiba tools when the server connects.

mcp.json

1{ 2 "mcpServers": { 3 "postshiba": { 4 "url": "https://app.postshiba.com/mcp", 5 "headers": { 6 "Authorization": "Bearer YOUR_API_KEY" 7 } 8 } 9 } 10}

The AI page in the dashboard shows this config for each agent. Right after you create a key there, it fills the key in.

Other agents

Your API key is the Bearer token. Every client sends it as Authorization: Bearer YOUR_API_KEY.

Claude Code, from your project folder:

claude-code.sh

1claude mcp add --transport http postshiba https://app.postshiba.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Codex reads the key from an environment variable, so it stays out of the file. Add this to ~/.codex/config.toml, then run export POSTSHIBA_API_KEY=YOUR_API_KEY in your shell profile.

config.toml

1[mcp_servers.postshiba] 2url = "https://app.postshiba.com/mcp" 3bearer_token_env_var = "POSTSHIBA_API_KEY"

Windsurf uses serverUrl in mcp_config.json:

mcp_config.json

1{ 2 "mcpServers": { 3 "postshiba": { 4 "serverUrl": "https://app.postshiba.com/mcp", 5 "headers": { 6 "Authorization": "Bearer YOUR_API_KEY" 7 } 8 } 9 } 10}

Any other client that supports Streamable HTTP with custom headers works with the same URL and header.

The key must go in the Authorization header. A token in the query string is rejected. Use app.postshiba.com, not postshiba.com.

What the tools can do

Key	Tools
Send only	Four tools: `whoami`, `send_email`, `send_template_email`, and `send_on_cluster`.
Full access	Every `/api/v1` endpoint in the REST API, such as `create_cluster`, `create_sending_domain`, `send_email`, and `list_team_message_events`.
Support	Five tools: `whoami`, `lookup_recipient`, `get_analytics`, `get_status`, and `destroy_suppression`. See Ask your assistant.

Pick the smallest key that does the job. An assistant acts on whatever it reads, including text in emails, web pages, and files, so a prompt injection can call any tool the key allows. Use a Full access key while you set things up, then delete it if you don't need it. Give an agent that only sends mail a Send only key.

The team comes from the key, so tools never take a team id. MCP requests are limited to 600 per minute per key.

Send gates match REST. While your account is pending production approval, sends go only to team member emails, live inbox addresses, and inbox forward-to addresses. Anything else returns 403 kyc_required. See Does PostShiba require production approval?

Secrets stay out of tool results

MCP removes secrets from every response: webhook signing secrets, inbox webhook_secret, DKIM private keys, and SMTP passwords. Copy those from the dashboard.

The one exception is create_smtp_credential, which returns the new password once. Cluster create issues a default SMTP user but hides its password, so call create_smtp_credential when the assistant needs one.

Prompts to try

Paste one of these into Cursor after the server connects. The dashboard's AI page has the same prompts.

first-send.txt

1I've signed up to PostShiba and have set up my first cluster. Could you help me get set up for our first send? Set up our sending domain, get SMTP credentials, and work out how to get our app configured to use it. Also help me with adding the DNS records or telling me what to do whilst you work on the code

create-cluster.txt

1Create a shared-IP cluster for this team. Name it after the team. A pending team can create one. If create_cluster returns 403 kyc_required, the team already has a cluster and needs approval for another. KYC is not an MCP action. If it returns payment_required, stop. Poll get_cluster until sending_ready is true before you send. Until the team is approved, send only to team member emails, live inbox addresses, and inbox forward-to addresses. Anything else is 403 kyc_required.

create-credentials.txt

1Create an SMTP credential on the cluster with create_smtp_credential so the password appears once. Cluster create already issues a default user and hides the password. Do not try to send over SMTP through MCP.

send-test-email.txt

1Send a sandbox message with send_on_cluster and sandbox true. Do not use send_email for a sandbox send. A live send needs sending_ready, a verified From domain, and a live credential. MCP cannot set Idempotency-Key. Never use the whoami email as From. Omit from or use a verified sending domain.

create-mailbox.txt

1Create an inbox with create_inbox. Omit host and sending_domain_id for a hosted address. For a domain-bound address, set local_part and host to one of your sending domains or a subdomain of it; sending_domain_id is inferred from host. The domain may still be waiting on DNS. The inbox starts receiving once it verifies, so ask me to publish the MX record together with DKIM and return-path. Inbox create is open while KYC is pending. MCP redacts webhook_secret. Copy signing secrets from the dashboard inbox page, not from MCP.

import-dkim.txt

1Import an existing DKIM private key for a sending domain that is migrating to us. Use create_sending_domain or update_sending_domain with dkim_manual true, the current selector, and the RSA PEM in dkim_private_key. MCP redacts private keys in responses. I will publish a TXT at {selector}._domainkey.{domain} matching dkim_txt, not a CNAME. Then call verify_sending_domain. Refreshing keys with refresh_sending_domain breaks authentication and sending until I publish the new TXT.

send-from-domain.txt

1Send from an address on a verified sending domain, not from the hosted inbox. Call create_sending_domain. For a new domain, wait while I publish the DKIM and return-path CNAMEs, then call verify_sending_domain. To bring an existing key, set dkim_manual true and dkim_private_key to the PEM, publish the TXT yourself, then verify. MAIL FROM cannot be an inbound.postshiba.com address. Never use the whoami email as From. Omit from or use a verified sending domain.

CLI skill

The postshiba CLI ships an agent skill that uses the same API key. Install it with postshiba skills install or npx skills add postshiba/postshiba-cli. It is also in the PostShiba Cursor plugin. See Send emails with the CLI.