MCP quickstart

By the end of this page an AI agent will be working in a Cypress organization of its own, a sandbox: made-up data, every tool open, and nothing reaching a real dealer, buyer or contact. Everything it does there works the same way in a live organization. You need an MCP client (Claude Code, Cursor, Claude Desktop or any other) and about ten minutes.

0. Try the Manual first (no key)

The Cypress Manual server searches and reads these docs. It holds no customer data and takes no credential, so it is the quickest way to see an agent work with Cypress:

claude mcp add --transport http cypress-manual https://app.getcypress.ai/api/mcp/manual

Ask your agent "How do I connect an agent to Cypress?". It calls search_manual, then read_manual_page, and answers from this documentation.

1. Get a sandbox

Ask your Cypress contact for a sandbox. A Cypress Manager makes it in Settings › Developers › Sandboxes and hands you three things:

• a test key, starting cyp_test_, shown once. It acts on the sandbox only: a test key used on a live organization, or a live key on a sandbox, answers 403 KEY_ENVIRONMENT;
• the addresses of the two servers that need it, Cypress Operate (work in the organization) and Cypress Intelligence (read what Cypress knows);
• the commands that connect Claude Code to them:

claude mcp add --transport http cypress-operate "https://app.getcypress.ai/api/mcp/operate" --header "Authorization: Bearer cyp_test_…"
claude mcp add --transport http cypress-intelligence "https://app.getcypress.ai/api/mcp/intelligence" --header "Authorization: Bearer cyp_test_…"

The sandbox already holds eleven cars and vans (eight unlisted, two on the market with offers waiting from a demo dealer, one sold and in its closing), four planning vehicles, a small CRM book (two companies, four contacts, a deal and three tasks) and a buy plan. Everything is listed in Sandbox.

2. Connect your client

Every client needs the same two things: the server's address, and the header Authorization: Bearer cyp_test_….

{
  "mcpServers": {
    "cypress-operate": {
      "url": "https://app.getcypress.ai/api/mcp/operate",
      "headers": { "Authorization": "Bearer cyp_test_…" }
    }
  }
}

{
  "mcpServers": {
    "cypress-operate": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.getcypress.ai/api/mcp/operate", "--header", "Authorization:${CYPRESS_AUTH}"],
      "env": { "CYPRESS_AUTH": "Bearer cyp_test_…" }
    }
  }
}

Check where you are. The client shows the server as Cypress Operate (sandbox), and the instructions it hands the agent say "…a SANDBOX organization: its data is made up and nothing reaches real dealers, buyers or contacts…". On a live organization the title has no "(sandbox)": that is how an agent, and you, can always tell the two apart.

The agent is shown Cypress's core tools: thirteen tools for the everyday work, and every other operation through discover. Nothing to ask for: they are the default.

3. Look around

Ask "What's in our fleet?". The agent calls find with type: vehicle and limit: 20 (a page holds 10 unless it asks for more), and finds eleven cars and vans, all in Texas: eight unlisted (DRAFT), a Camry, a Malibu, a Sentra, a Transit, a RAV4, a ProMaster, an Accord and an F-150; a Tucson and a Sportage on the market (LISTED); and a Grand Cherokee already sold (OFFER_ACCEPTED), in its closing.

Your own systems have their own ids for records, and Cypress keeps them. Ask "Who is contact C-101 in our CRM?". The agent looks the record up by your id: find with type: contact and externalId: "sandbox-crm:C-101" finds Maria Delgado at Lone Star Auto Group. See Your own ids.

4. Put the Camry on the market, dry run first

Ask "List the 2022 Camry at $24,500 with a $22,000 floor, live now. Do a dry run first." Every write takes dryRun: the same checks as the real call, nothing written. The agent calls launch with dryRun: true:

{
  "dryRun": true,
  "wouldCreate": { "vehicleId": "…", "channels": ["MARKETPLACE"], "listingMode": "IMMEDIATE", "floorPrice": 22000, "buyNowPrice": 24500 },
  "launch": { "wouldLaunch": false, "alreadyLive": false, "missing": ["condition"], "blocked": "missing condition to go live" }
}

The car can't go live without its condition. Tell the agent it is in good condition: it finds the operation with discover ("edit a vehicle"), then calls run_write with edit_vehicle and condition: "GOOD". It runs the dry run again ("wouldLaunch": true), then makes the real call. Cypress answers with the listing, "status": "ACTIVE" and "launched": true, and the Camry is now LISTED.

Retries are safe. A good agent sends an idempotencyKey with every write. If the connection drops and it sends the same call again with the same key, Cypress answers the first answer and lists the car once.

In a sandbox the listing is real but only demo dealers see it: no real buyer will ever see a sandbox car.

5. Meet a decision a person keeps

Ask "Email Maria the Q4 sedan list." The agent calls run_write with email_contact, and Cypress does not send anything:

{
  "status": "NEEDS_PERSON",
  "code": "PEOPLE_ONLY",
  "message": "An email in your organization's name goes out from a person. Log what happened, or give a person the task.",
  "decisionLink": "/go/contact/…"
}

Some decisions are always a person's, whoever asks: an email in your organization's name, an offer below the floor, approving a quarter's plan, and others. The agent gets a link to the record in Cypress so it can hand the decision over. Here it does what the message suggests and calls log with kind: task: "Send Maria the Q4 sedan list", on her contact, for a person to pick up. What an agent may and may not do is in What an agent can and cannot do.

6. Look at the offers

Ask "What offers are waiting?". The agent calls find with type: offer and status: NEW: three, $26,800 and $24,000 on the Tucson and $23,500 on the Sportage. Never the buyer's name: Cypress does not tell a seller who the buyer is.

Ask "Accept the $24,000 offer on the Tucson." The agent calls answer_offer with answer: accept and a dry run. The Tucson's floor is $25,500, so Cypress answers NEEDS_PERSON, with PEOPLE_ONLY and the words "Accepting an offer below the floor is for a person at the seller, never an integration or an agent.", and a link to the offer. The other two are at or above their floors, so an agent may accept or counter them.

7. Take a car off the market for a while

Ask "Take the Camry off the market for now, it's going back on rent." The agent finds pause_vehicle with discover and runs it with run_write, the same Pause as the vehicle's page in the app:

{ "success": true, "status": "ON_HOLD", "offersWithdrawn": 0 }

A pause withdraws any open offers and tells the buyers, so the answer says how many it withdrew.

Start over

The agent can put the sandbox back as it was made at any time: run_destructive with reset_sandbox (or POST /api/v1/sandbox/reset). The same test key keeps working, and the apps you connected stay connected. One reset a minute.

If the key may have leaked, ask your Cypress contact instead: their reset issues a new test key, and the old one stops working.

Next