MCP servers

Cypress runs three servers for agents that speak the Model Context Protocol: give your agent the address and a credential, and it can work in Cypress and read what Cypress knows, under the same rules as the app; the manual needs no credential at all. Since 1.5.0.

Signing in

Every request carries a credential, exactly as the REST API takes it:

• An API key as a bearer (Authorization: Bearer cyp_live_…, or cyp_test_… for a sandbox). Most MCP clients let you set a header. Never test with a live key: see Live and test keys.
• A Connect Cypress token, for an app or an agent your organization connected. A request without a credential answers 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/api/mcp/<server>", which names Connect Cypress as the authorization server. An MCP client needs no registration with Cypress: it signs in with a client ID metadata document, or registers itself at the server settings' registration_endpoint (RFC 7591), and its token acts for the admin who approved it.

A credential that was sent and is not valid (unknown, revoked or expired) answers 401 with WWW-Authenticate: Bearer error="invalid_token" and its own message; one that was never sent gets the bare challenge above.

Cypress staff connect with a CM token (cyp_cm_…, made by a Cypress Manager in Settings › Developers). It acts as that person, under the same rules as in the app: for the organization named in the Cypress-Organization header, in ?organization= on the server's address, or in organizationId on each organization's tool; the staff tools (archiving a vehicle for Cypress, for example) need none. A connection is told who acts and for whom, and _meta carries "ai.getcypress/actor": "STAFF".

Where a connection acts. On initialize and server/discover, Operate and Intelligence say whether the credential's organization is LIVE or a SANDBOX: _meta carries "ai.getcypress/environment", a sandbox's server title ends in "(sandbox)", and the instructions open with it. In a sandbox nothing reaches a real person (emails, campaign sends, reminders and signing links are recorded and answered simulated), so an agent may try every write tool there.

The tools a client sees are those the credential's scopes allow: a key with tasks:read and tasks:write sees the task tools and nothing else. Cypress Intelligence needs insights:read (and buy-planning:read for buy matches). See Organization & scopes.

Try it

The MCP quickstart walks an agent through its first ten minutes in a sandbox, with the configuration for Claude Code, Cursor, Claude Desktop and other clients. In short: the Manual needs nothing. In Claude Code, for example:

claude mcp add --transport http cypress-manual "$BASE/api/mcp/manual"

Operate and Intelligence take an API key from Organization → Integrations, with the scopes you want the agent to have:

claude mcp add --transport http cypress-operate "$BASE/api/mcp/operate" \
  --header "Authorization: Bearer cyp_test_…"

Operate shows an agent the core tools by default: thirteen tools for the everyday work, and every other operation through discover.

Try it on a sandbox first: its test key acts where nothing reaches a real person.

Add an area to the address to show its tools beside the core ones, ?toolsets=core,crm (see Tools by area). Any MCP client takes the same two things, an address and a header. The MCP Inspector (npx @modelcontextprotocol/inspector, transport Streamable HTTP) lists the tools and calls them one at a time. Plain HTTP works too:

curl -X POST "$BASE/api/mcp/manual" \
  -H "content-type: application/json" -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_manual","arguments":{"query":"connect an app"}}}'

The protocol

All three servers speak Streamable HTTP, statelessly: one JSON-RPC message per POST, answered with JSON. They serve the current revision, 2026-07-28 (the version, client and capabilities in each request's _meta, mirrored in the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers; server/discover answers the supported versions, capabilities and server; the version may also come as plain _meta.protocolVersion, or in the header alone), and clients of the handshake revisions 2025-11-25, 2025-06-18 and 2025-03-26, which open with initialize (no session is created; send the version you agreed on in MCP-Protocol-Version). Errors are the protocol's own: -32022 for a version the server does not speak (with the supported ones), -32020 when a header does not match the body, 404 with -32601 for an unknown method, 405 for GET and DELETE.

Tasks. Cypress Operate supports the Tasks extension (SEP-2663; server/discover lists io.modelcontextprotocol/tasks). An import, of vehicles (import_vehicles) or of CRM records (import_crm_records), runs in the background, so to a client that says it takes tasks (the extension in that request's _meta capabilities) an import that queued work answers a task handle instead of a result: resultType: "task", a taskId and pollIntervalMs. A vehicle import that queues both new vehicles and updates is one task that follows both. The client polls tasks/get until the task is completed, with the import's own answer as its result (an import that failed completes too, with an error result). Cypress staff without an organization on the connection name it on tasks/get with organizationId, as on a tool call. tasks/cancel and tasks/update are acknowledged; an import cannot be stopped once queued. A task id works only for the organization that started it, and every poll reads the import again as the caller. A client that does not take tasks gets the plain answer, with the batch to follow with get_import or get_crm_import.

What a tool answers. Every tool declares an outputSchema, and its answer is structuredContent that fits it, with the same JSON, compact, in the text block for clients that read text only. The schemas describe the answer loosely (no field is required, any may be null) so a real answer is never refused; on Operate they come from this API's own response schemas, two levels deep.

Cypress Operate

Its tools are generated from this API's own reference: each one takes the endpoint's path and query parameters as arguments and its request body as body, and is answered by the same code a REST call reaches. Every write, Planning's included, takes dryRun (the route's own: every rule checked, what would change said, nothing written) and idempotencyKey (a retry answers the same, once). A write that takes something away or cannot be taken back is annotated destructiveHint so a client asks the person first: accepting, declining or withdrawing an offer, sending a campaign now, taking a vehicle off the market, ending the sell strategy, and every tool that deletes, removes, archives, revokes or dismisses (a goal, a note, a photo, a location).

What follows is every operation Operate offers. An agent sees the core tools by default and reaches the rest through discover and run_*; a connection that asks for an area, or for all, is shown those operations as tools of their own.

Lists answer a page an agent can read: 10 records unless the call names a limit, each summarized (its own fields and links, without its lists, such as a closing's steps) unless it asks for view: "full". Read one record in full with its get_ tool. nextHref names the next page.

A write Cypress keeps for a person is not made. When the rules say a person decides (an email in your organization's name, an offer below the floor, a policy, the other side's closing step), the tool answers with status: NEEDS_PERSON, the reason, and a decisionLink, always: the record in Cypress where a person makes the call, or the screen for a decision that names no record. Give the link to a person; do not retry. A refusal that says what to fix is not a person's decision: an automation that uses a node your organization's automations may not contain comes back as an error with its findings, one per node, so the agent can change the graph and try again.

Cypress Intelligence

The privacy rules are the app's: a figure from a seller's floor goes only to that seller; market counts appear only from two dealers, and a sold range only from five sales by two sellers or more; the market board never shows your own organization or a name.

Cypress Manual

The platform manual and guides, the pages under /docs, for an agent that needs to know how Cypress works before it acts, or for anyone building on it. It holds no customer data, so it takes no credential: point the agent at the address and it is ready. It is limited to 120 requests a minute per caller, and answers 429 with Retry-After: 60 past that. Search ranks a page by the words of the question that are rare across the manual (common words such as "how" count for nothing), in its title, its path and its text, and meets "delist", "de-listing" and "delisting" as one word; a passage shown with a result starts at a sentence or a word and ends at a word.

Skills

The Manual also serves Cypress's workflows for agents as Agent Skills, over the MCP Skills extension: a client that supports skills lists them with skills/list and loads the one a job needs. Each is a SKILL.md that walks an agent through the work with the core tools, the rules included.

Every file comes with its SHA-256 digest and size, so a client can check what it loads. A client without skills can read the same files with resources/read.

Tools by area

An agent picks the right tool more reliably when it sees fewer of them. Each server groups its tools by business area, and a connection can ask for the areas its role needs on the server's URL:

https://app.getcypress.ai/api/mcp/operate?toolsets=closings,work
https://app.getcypress.ai/api/mcp/intelligence?toolsets=planning

The connection then sees those areas' tools only, among the ones its scopes allow. Areas never widen what a credential may do: asking for marketing without marketing:read shows nothing. Without toolsets, Operate shows the core tools (core), with the staff tools beside them for a CM token, and Intelligence and the Manual every tool they have. A tool outside the areas a connection asked for answers which executor or area reaches it. all shows every per-operation tool instead, for a gateway that brings its own tool search; core,crm shows the core tools and the CRM's own. A name the server does not have is an error (-32602, naming the areas it offers), never an empty list. The x-mcp-toolsets header works the same way, for clients that cannot change the URL.

Suggested areas by role:

Give each agent the scopes its role needs as well: the areas choose what it is shown, the scopes what it may do. Operate's instructions carry the same table, so an agent connected without toolsets reads which areas its job needs.

Switching a server off

Operate and Intelligence are on for every organization. An admin, or Cypress staff acting for the organization, switches either off in Settings › Connected apps › MCP servers; every request from the organization's credentials then answers 403, saying where to turn it back on.