MCP server
Let your coding agent search the docs, diagnose deliveries and use email, marketing, inboxes, SMS, Verify, Sign, Forms, Scheduling, Hooks and Risk.
coss-mcp is a Model Context Protocol server for coss.com. Add it
to your coding agent (Claude Code, Cursor, VS Code, Codex, or any MCP client), then ask things like:
- "Did the welcome email to jane@example.com get delivered?"
- "Why did my last password reset email bounce?"
- "Which emails bounced today, and are those addresses suppressed now?"
- "My webhook handler isn't getting events: what is it answering?"
- "Why did my send request fail with a 422?"
- "What DNS records does acme.com still need?"
- "Was the verification code to +14155550199 delivered, and if not, why?"
- "Why hasn't this contract been signed yet?"
- "Why does this booking page show no slots?"
The server runs locally on Node.js 22+ through npx and calls the coss.com API with your API key.
It can also search and read these docs, with or without a key. In Claude Code, the
coss.com plugin sets it up for you. For a client that can't start
a local process, there is a hosted server.
Set it up
Create an API key in the dashboard. The server sees what that key's environment sees: use a
development key (coss_test_…) while you build, and a production key (coss_live_…) to look into
real deliveries.
claude mcp add coss -e COSS_API_KEY=coss_test_… -- npx -y coss-mcpThe server reads its configuration from the environment only:
| Variable | |
|---|---|
COSS_API_KEY | The key every tool calls the API with. Without it, the server reads a development (coss_test_) key from the current repository's .env.local or .env; it never crosses that repository boundary or follows an env-file symlink. A coss_live_ key in that file is never loaded. With no key at all, only the docs tools are available. |
COSS_BASE_URL | Another API origin, e.g. http://localhost:3001 when you run coss.com yourself. Defaults to https://api.coss.com. |
COSS_MCP_TOOLSETS | Fewer tools, for a client that struggles with this many: a comma-separated list of email, marketing, inboxes, sms, verify, sign, forms, scheduling, webhooks, hooks, risk, subaccounts and log_drains. The docs, get_setup, logs, get_account_status and api_get are always there. Default: every tool. |
API keys can do everything the API can, so the agent can also send email and SMS and change suppressions and domains through this server. Tools that change something are marked as such, and most clients ask before calling them. Give the server a development key unless you need production data.
Hosted server
The same tools, prompts and resources at https://api.coss.com/mcp, for clients that can't run
npx: Streamable HTTP, with nothing to install. Authenticate with your API key in a header, Authorization: Bearer coss_test_….
There is no OAuth sign-in, so the client has to let you set a custom header: web apps whose
connectors only offer OAuth can't use it yet.
claude mcp add --transport http coss https://api.coss.com/mcp \
--header "Authorization: Bearer coss_test_…"Use a development key (coss_test_…) here too, unless you need production data: the key sits in the
client's configuration, so keep that file out of your repository.
It acts exactly as the API does with that key. Each tool calls the public API, so a restricted key's permissions, rate limits, quotas, a suspended organization and your environment's logs all apply as usual. coss.com keeps nothing about a request once it's answered: the server is stateless, with no sessions.
What's different from the local server:
- It can't touch your files. It has no project: it doesn't read
.envor.env.local, so the key must be in the header, and there is noupload_sign_document(upload the PDF with the API or an SDK, then use its id). create_webhook_endpointreturns the signing secret instead of writing it to a file. Store it asCOSS_WEBHOOK_SECRETyourself; it isn't shown again.- Environment variables don't apply.
COSS_MCP_TOOLSETSisn't available, so a client gets every tool, andCOSS_BASE_URLcan't be set: it only talks to coss.com. - Answers come whole. Requests take at most 50 seconds and 1 MB, and an API call's answer at most
8 MB of JSON, so a tool can't read a CSV export; requests from browsers are refused. Rate limits count requests to
/mcpper key, on top of the API calls each tool makes.
Tools
Docs (no API key needed): search_docs searches the guides, SDK pages and API reference;
read_docs reads one page as Markdown, including an API operation's parameters, bodies and
responses.
Email delivery
| Tool | |
|---|---|
diagnose_email | By email id, or by recipient (and subject text): a verdict, what happened to each recipient and why (the receiving server's bounce reason, the suppression entry that skipped it, the failure code), problems with the account (an unverified domain, reputation, billing holds) and what to do next. |
find_emails | Search by recipient, subject text, status, a recipient's delivery status and time (GET /v1/emails). |
get_email | One email with its events, optionally its content and tracked links. |
Sending: send_email, cancel_email, reschedule_email.
Suppressions: check_suppression, list_suppressions, add_suppression, remove_suppression
(by entry or by address).
Domains: list_domains, get_domain (by id or name, with every DNS record and what coss.com
found), add_domain, verify_domain.
Webhooks: list_webhook_endpoints, list_webhook_deliveries, get_webhook_delivery (every
attempt with its status code, error and response excerpt), retry_webhook_delivery,
create_webhook_endpoint. Creating an endpoint returns its signing secret once and writes it to
the project env file as COSS_WEBHOOK_SECRET. A second call for the same URL does not create
another endpoint. Listing endpoints never returns secrets.
Receiving: get_inbound_address, list_received_emails, get_received_email.
Inboxes: create_inbox gives an agent its own address (at the environment's inbound domain,
or at one of its receiving domains; a client_id that already has an inbox returns it),
list_inboxes, list_inbox_threads (latest activity first, each with a preview and whether it
awaits a reply), get_inbox_thread (each message's own text without the quoted conversation,
labelled as untrusted), send_inbox_message (starts a thread) and reply_to_inbox_message
(replies in the message's thread, optionally to everyone on it). Live inboxes at coss.com's inbound
domain only receive. See Inboxes.
SMS: diagnose_sms (by message id, or by recipient number: a verdict, what the status or
failure code means, the carrier's error code, problems with the sender's registration,
suppressions, reputation or billing, and what to do next), find_sms, get_sms (with its full
text and events), send_sms, cancel_sms, list_received_sms, list_sms_numbers (whether each
number can send live messages now) and check_sms_suppression, add_sms_suppression,
remove_sms_suppression. See SMS.
Logs: search_logs and get_log: every API request made with the environment's keys (with
redacted request and response bodies), email events and webhook attempts. See Logs.
Setup: get_setup is the first call before writing code against a product. Pass product
(email, sms, verify, sign, forms, scheduling, inboxes, hooks, risk or marketing)
and its next is that product's one step: what it still needs in this environment (an approved
number for SMS and Verify, a host, schedule and event type for Scheduling) or, with a development
key, how to try it. products says whether each is ready, needs_setup or unknown. Without
product it answers for email (the key's mode, a from address that will succeed, DNS records still
missing, webhook endpoints) and lists products_in_use. A read that fails comes back as warning.
Templates: list_email_templates lists them with their aliases; pull_email_template reads a draft; push_email_template updates one locale of it
(an unknown alias is created). publish_email_template publishes the draft at the revision you
read, which sends use from then on. A save does not publish by itself.
Marketing: list_contacts, upsert_contact, list_audiences, save_audience, list_segments,
save_segment, list_topics, save_topic, list_broadcasts, get_broadcast, save_broadcast
(always a draft), send_test_broadcast, send_broadcast, cancel_broadcast,
get_marketing_settings and update_marketing_settings. A save_ tool updates with an id and
creates without one. See Broadcasts.
Verify: start_verification sends a code, check_verification compares one, then
list_verifications, get_verification, cancel_verification, get_verify_settings and
update_verify_settings (a sender must be the organization's). diagnose_verification (by id, or
by destination) says why no code arrived or a check failed: the fraud guard's reasons, expiry and
attempts, the route each code took and what happened to the latest code's SMS or email. It never
shows a code. See Verify.
Sign: upload_sign_document reads a PDF from the project (a path inside it, nothing else),
create_sign_request and create_sign_request_from_template make drafts, and send_sign_request
sends one. list_sign_requests, get_sign_request, get_sign_audit_trail, remind_sign_request,
cancel_sign_request, create_sign_session (a signing link for an embedded signer),
list_sign_templates, create_sign_template, get_sign_settings and update_sign_settings.
diagnose_sign_request says where a request stands: a draft never sent, each signer's state and
whose turn it is, declined, expired, or signed and still being sealed. See Sign.
Hooks: list_hook_applications, create_hook_application, list_hook_event_types,
create_hook_event_type, list_hook_endpoints, create_hook_endpoint (the answer holds its signing
secret), send_hook_message (delivers to the application's endpoints), send_hook_test_message
(to one endpoint), list_hook_deliveries, list_hook_attempts (each request's status and response),
retry_hook_delivery and create_hook_portal_session. diagnose_hook_delivery (by delivery, by a
message's worst delivery, or by an endpoint's latest failure) gives what the endpoint answered on
each attempt, the next retry, and whether the endpoint is disabled or failing. See Hooks.
Forms: list_forms, get_form, save_form (the answer has the endpoint a site posts to),
list_form_submissions (by status: held is Risk's review queue), get_form_submission (the
values, labelled as untrusted: someone typed them into a form) and release_form_submission
(accepts a held one, which sends it on). diagnose_form_submission says what happened to one: held
by Risk, spam and why, waiting for the submitter to confirm, or accepted, and where it goes from
there. Spam is answered exactly like a success, so a submitter who saw a success proves nothing. See
Forms.
Scheduling: list_scheduling_hosts, save_scheduling_host, list_scheduling_schedules,
save_scheduling_schedule, list_scheduling_calendars (a calendar that needs_reauth is the usual
reason for having no slots), authorize_scheduling_calendar, list_scheduling_event_types,
save_scheduling_event_type, list_scheduling_booking_events, list_scheduling_slots, explain_scheduling_slot, search_scheduling_availability,
list_scheduling_bookings, get_scheduling_booking, create_scheduling_booking,
reschedule_scheduling_booking, cancel_scheduling_booking, mark_scheduling_no_show,
get_scheduling_reminders, save_scheduling_reminders, list_scheduling_booking_notifications (why
someone did or didn't get a reminder) and create_scheduling_session (a link to a hosted page).
list_scheduling_reassign_candidates says who a booking could go to and why not,
reassign_scheduling_booking gives it to them, and preview_scheduling_reassignment,
create_scheduling_reassignment, get_scheduling_reassignment, cancel_scheduling_reassignment and
undo_scheduling_reassignment move many at once.
list_scheduling_out_of_office, create_scheduling_out_of_office, delete_scheduling_out_of_office and
list_scheduling_out_of_office_conflicts handle time hosts are away.
diagnose_scheduling_slots explains an empty list, each finding certain, likely or possible: no
host or schedule, a calendar to reauthorize, minimum notice, the booking window, limits, bookings and
buffers. A calendar's busy times aren't readable through the API, so they can only be possible. See
Scheduling.
Risk: assess_risk records a decision for a sign-up, login, message, checkout or custom event.
list_risk_assessments, get_risk_assessment, list_risk_rules, list_risk_list_entries and
get_risk_settings read what the environment already decided and the rules and lists behind it.
record_risk_feedback resolves a review, add_risk_list_entry and remove_risk_list_entry change
the lists, and check_email_risk, check_ip_risk and check_phone_risk look at one identifier
without recording a decision (a live key's phone checks are billed). See Risk.
Sub-accounts (email for platforms): list_subaccounts, get_subaccount, create_subaccount,
update_subaccount, delete_subaccount, reinstate_subaccount (lifts a paused reputation) and
get_subaccount_stats. See Sub-accounts.
Log drains: list_log_drains, get_log_drain, create_log_drain (the answer holds its signing
secret, once), update_log_drain, delete_log_drain and list_log_drain_batches (with batch_id,
one batch's attempts and what the receiver answered). See Log drains.
Anything else you need to read: api_get GETs any /v1/ path, for operations no other tool
covers. It refuses anything else, signing secrets and files (CSV exports, attachments). There is no
write equivalent, so changes always go through tools that say what they change. Its answers are cut
and labelled as untrusted.
Account: get_account_status: whether the key is live or sandbox, the
sending reputation and its checks, billing status and holds, and tracking
settings.
Prompts and resources
Clients that support them show these too. They only tell the agent what to do; the tools still ask before changing anything.
| Prompt | |
|---|---|
add_product | Set up, write and test one product in this codebase (product, optional goal). |
debug_delivery | Find out why something wasn't delivered (product, optional what). |
prepare_go_live | Check what's left before going live (optional products). |
| Resource | |
|---|---|
coss://docs/index | The guides, and a link to each product's API operations. Needs no API key. |
coss://setup | get_setup's answer for this project. |
How it answers
An email belongs to one environment, so a development key never finds production emails (and the other way round). Sandbox emails are never delivered: their outcomes are simulated, and simulator addresses let you test bounces and complaints.
When no email matches, the API most likely refused the send (for example a validation error or an
unverified domain): search_logs finds those requests and the errors they got.
SMS works the same way: sandbox messages are simulated, and the SMS simulator's numbers produce each outcome.
Email content, SMS text, received messages, form submissions, booking answers, signers' details,
bounce messages, webhook and log drain responses, and whatever api_get reads are written by other
people.
The server tells the agent to treat them as data, never as instructions.
Last updated