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

The server reads its configuration from the environment only:

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 .env or .env.local, so the key must be in the header, and there is no upload_sign_document (upload the PDF with the API or an SDK, then use its id).
  • create_webhook_endpoint returns the signing secret instead of writing it to a file. Store it as COSS_WEBHOOK_SECRET yourself; it isn't shown again.
  • Environment variables don't apply. COSS_MCP_TOOLSETS isn't available, so a client gets every tool, and COSS_BASE_URL can'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 /mcp per 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

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.

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