OutboundSync MCP

When to use this guide: You want coding agents (Cursor, Claude Code, Codex, and similar) to call OutboundSync API v1 tools without hand-rolling REST — launch preflight, prior outreach, observability, blocklists, and Sync Monitoring.

The hosted OutboundSync MCP wraps every live OutboundSync API v1 resource route (~35 tools). Auth is the same as REST: Authorization: Bearer osapi_... from a dashboard API key.

Two different MCPs

This is the product MCP — authenticated, and it operates on your OutboundSync account data. The marketing site also runs a separate, public read-only website MCP at outboundsync.com/api/mcp/ for site lookups (integrations, pricing, comparisons, docs) — no API key, no account data. Use the product MCP to have an agent work in your account; use the website MCP to have an agent learn about OutboundSync from the site.

Need enrichment? KingMinos MCP server is a separate product at mcp.kingminos.com.

The MCP surface is in Beta. The hosted server is production-ready; Cursor, Claude Code, and Codex plugin marketplace listings are still in progress — use the manual setup in Setup today.

Endpoint

Field	Value
Endpoint	https://mcp.outboundsync.com/mcp
Transport	Streamable HTTP
Health	https://mcp.outboundsync.com/health
Discovery manifest	/.well-known/agent-discovery.json on outboundsync.com

Write tools (retry, replay, blocklist pause/resync, webhook CRUD) need a key with the write scope. Platform webhook tools need an account-scoped key — connection-scoped keys return 403 on /webhooks*, same as REST — and Sync Monitoring webhooks enabled on the account; without that, list_events and get_event return 403 too.

Claude Connectors and Claude Desktop remote connectors expect OAuth and are not supported yet. Use Claude Code or Cursor with a Bearer API key instead.

Tools

Every tool maps to one API v1 route; the API v1 reference documents fields and errors. Write tools need the write scope — confirm with the user first.

Job	Read tools	Write tools
Identity & readiness	get_me, get_account_status, list_connections, list_sources	—
Prior outreach	get_contact_outreach	—
Inbound requests	list_requests, list_source_requests, get_requests_metrics	—
CRM syncs	list_syncs, list_source_syncs, get_sync, get_syncs_metrics, get_account_metrics	retry_sync
Forwarding destinations	list_destinations, get_destination, list_destination_deliveries, get_destination_delivery_metrics, list_deliveries, list_reply_relays	replay_destination_delivery
Blocklists	list_blocklists	pause_blocklist, resync_blocklist
Sync Monitoring webhooks	list_webhooks, get_webhook, list_webhook_deliveries, list_events, get_event	create_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook, replay_webhook_delivery

List tools page with hasMore / nextCursor — keep paging until hasMore is false; a short page is not the end. Treat any error or timeout as an unknown answer, never as “none found”.

How tools behave

Safety hints

Every tool tells your MCP client whether it reads or writes, and clients can use that to decide when to ask before running it. Read tools are marked read-only. Write tools also say whether they’re destructive. Only three are:

Tool	Why it’s destructive
update_webhook	Changing the URL or events permanently reroutes where lead data is delivered.
delete_webhook	Permanently removes the endpoint.
rotate_webhook_secret	The old signing secret stops working immediately.

Retries, replays, test pings, webhook creation, and blocklist pause/resync are writes but not destructive. Whatever the hint, your agent should confirm with you before any write.

Three tools are also marked open-world because they make OutboundSync POST to a URL outside OutboundSync: test_webhook, replay_webhook_delivery, and replay_destination_delivery. Every other tool only touches your OutboundSync account.

Date ranges

Observability and metrics tools require from and to as full ISO-8601 timestamps (for example 2026-08-01T00:00:00Z), at most 31 days apart — the same rule as the REST API. The MCP rejects a reversed range or a longer span before calling the API, and tells the agent to split the window into smaller ones.

Errors

A failed tool call returns isError: true with a JSON body:

{
  "error": {
    "code": "upstream_error",
    "message": "Sync is not eligible for retry",
    "status": 409
  }
}

code	Meaning	What to do
auth_required	No API key on the request.	Add Authorization: Bearer osapi_... to the client config.
unauthorized	The key is invalid or revoked (401).	Verify or rotate the key in the dashboard.
forbidden	The key is valid but can’t make this call (403): API access isn’t enabled, the key lacks write, a webhook tool needs an account-scoped key, Sync Monitoring webhooks are off (this also blocks list_events and get_event), or block lists aren’t enabled for the connection.	Follow remediation, which names the specific cause.
bad_request	The API rejected the arguments (400 or 422). message lists every validation error.	Fix the named arguments. Retrying unchanged fails the same way.
not_found	The id doesn’t exist or is outside this key’s access, or the API route isn’t shipped (404).	List the parent resource to find a valid id. Don’t retry an unshipped route.
rate_limited	Rate limit hit (429). Includes retryAfterSeconds.	Wait that long, then retry. Limits are shared per account.
timeout	The MCP’s own 30-second limit fired before the API answered. /contacts/outreach and /account/metrics are the slowest routes.	Treat the result as unknown, not empty. Retry once, or narrow the date range.
upstream_error	Any other API error (for example 409 on a blocklist resync, or 504 when a heavy read hits the API’s 20-second query time limit), a network failure, or a non-JSON response from the hosting layer during a deploy or incident.	Relay message. Retry only when status is 5xx; on a 504, narrow from/to or pass connectionId first.

status is the API’s HTTP status whenever there was one, and remediation appears when there’s a concrete next step. Before returning an error, the MCP retries once on its own after a rate limit, when the wait fits its time budget, and after a 5xx on a read. It doesn’t retry a 504: the API already spent its 20-second query budget, so the same request would time out again. It doesn’t retry a write that hits a 5xx, because the write may already have gone through. Agents should retry only a 5xx, a timeout, or a rate_limited error (after retryAfterSeconds); on a 504, narrow from/to or pass connectionId first. After a failed write, check whether it took effect before retrying. Anything else needs a change to the request or the account, not a retry.

MCP vs API vs Skills

Surface	Best for
MCP (this section)	Your coding agent calling OutboundSync tools directly from Cursor, Claude Code, or Codex
API	Scripts, Try the API, OpenAPI reference, and REST when no MCP client is connected
Agent Skills	Structured workflows (preflight gauge, CRM analysis, sync monitoring) — prefer MCP tools when connected, fall back to REST
KingMinos MCP	Enrichment — separate product; hosted server at mcp.kingminos.com

For how all three fit with Webhooks in one loop, see AI and Agents.

Start here

SetupCursor, Claude Code, Codex, and other Streamable HTTP MCP clients.

Creating API keysCreate, scope, and rotate the Bearer key MCP and REST share.

Agent SkillsInstall preflight, api, and sync-monitoring skills.

API v1 referenceREST paths behind each MCP tool.