MCP server

Connect Claude, Cursor, ChatGPT or any MCP client to your ShowPilot workspace with sixteen tools that reach every API operation.

ShowPilot runs a remote MCP server at https://api.showpilot.com/mcp. Point an MCP client at it, sign in with your ShowPilot account, and the client can read your tours, agents, visitors and insights, propose and apply edits, and call any operation in the API.

Connect

Most clients take a URL and handle sign-in themselves. When the client first connects it is sent to ShowPilot's sign-in, you pick the organization to work in, and the client receives a token for it. No API key is needed.

claude mcp add --transport http showpilot https://api.showpilot.com/mcp

For a server-side agent without a person to sign in, pass an API key as the bearer token instead; the same server accepts both.

What your account can do

A user token carries the organization you chose and the role you hold there. Admins get every scope an API key can be minted with; members get the read scopes plus knowledge queries. A key's scopes are exactly what it was minted with.

Ask whoami and the answer names the organization, your role in it, and how it was chosen.

If you belong to several organizations

Some clients connect before they can ask you to pick one. When that happens the server falls back to your first organization by name, and whoami says so — organization_chosen_by: "default", with a warning.

In that state reads run against the default, but anything that changes something refuses rather than write to a guess. The refusal lists the organizations you belong to. Name one and retry:

{ "kind": "skill", "id": "objection-pricing", "spec": { }, "org": "acme" }

org takes an organization id or slug and works on every tool. To fix it for the whole connection instead, send X-ShowPilot-Org: <organization id or slug> as a header, or reconnect with a client that asks you to choose.

The sixteen tools

The server does not expose one tool per endpoint. Harnesses have small tool budgets, so ShowPilot takes one slot per job and still reaches everything.

They arrive in this order, and the order is the advice: start at the top, and only reach the bottom two when nothing above fits.

Tool	What it does	Changes things
`whoami`	The organization you are acting in, your role there, live or sandbox, and everything you are allowed to do.	No
`search_visitors`	Find people by what they asked, not what they clicked. Web-search syntax over their own words.	No
`get_visitor_journey`	One person, whole: who they are, their conversations, tours, verdict, and what the agent still owes them.	No
`get_account_brief`	One company before you call them: CRM stage, owner, open deals, everyone from it, and their unanswered questions.	No
`get_conversation`	One conversation in order. Identities masked unless your credential carries the transcripts scope.	No
`get`	Read one thing whole, as the document you would edit: tour, hub, agent, visitor, conversation, lead, follow-up, meeting, segment, webhook, knowledge base or source, skill, tour spec, agent script. Carries the version `apply` needs.	No
`query_insights`	The workspace pulse over a window, or per-tour plays, completion and calls to action.	No
`weekly_digest`	What happened and what moved, against the window before. Answers "is this working".	No
`find_knowledge_gaps`	What visitors asked that the agent could not answer, in their own words, with why it stalled.	No
`find_sales_ready_accounts`	Companies worth a call right now — engaged visitors grouped by company, strongest intent first.	No
`propose`	Check a change before making it: the diff against the live document, plus any rule it breaks.	No
`draft_offer`	Turn a sentence about who an offer is for into a whole offer — copy, what converting collects, and the gates. Grounded in what your workspace really has.	No
`apply`	Make the change, with the version you read. A concurrent edit returns `409 stale` rather than overwriting. Does not publish.	Yes
`describe_api`	The exact input an operation takes, when a call was rejected and you need the schema.	No
`search_api`	Escape hatch: find any operation in the API by words.	No
`execute`	Escape hatch: call any operation by name. Use it for work the tools above do not cover.	Yes

Each tool carries MCP annotations, so a client knows before it calls whether a tool only reads, whether repeating it is safe, and whether it may retry on its own. apply and execute are the only two marked as changing anything.

Two resources are also published: showpilot://api/operations, the full operations table with input schemas, and showpilot://api/docs, links into this site.

Finding people by what they said

search_visitors is the search no other analytics can run. ShowPilot keeps an index over what each visitor asked and said — their chat turns, the questions the agent escalated, its own summaries, their qualifying answers — so you can ask for the people, not the pageviews:

{ "asked": "security OR SOC2 OR \"single sign-on\"", "identified": true, "lastSeenWithinDays": 30 }

asked takes web-search syntax: OR, quoted phrases, and - to exclude. Combine it with identified, hasCrm, minIntent, lastSeenWithinDays or toursWatched; the facts and the text narrow together. It refuses an empty search rather than handing back everyone.

From a result, get_visitor_journey opens one person and get_account_brief opens the company behind them — the CRM stage, the owner, open deals, and the questions that company asked which nobody answered. The brief works from the enriched domain, so it answers for a company whose visitors have never filled in a form.

The three questions only ShowPilot can answer

Clicks are everywhere. What a visitor actually asked is not, and three tools are built on it.

weekly_digest gives the window against the one before it, with every metric ranked by how much it really moved — and missingDays naming any day not folded yet, so partial figures read as partial rather than as a decline.

find_knowledge_gaps is the one to start with. Every question the agent could not answer, in the visitor's own words, with why it stalled and whether a human has since answered. That list is the raw material for knowledge, an objection page, or a skill. It comes back unclustered on purpose: your model groups them better than a pattern would, and normalized collapses exact repeats without one.

find_sales_ready_accounts groups recently engaged visitors by company, strongest intent first, with whether your CRM already shows an open deal and who owns it. There is no fit or ICP score — engagement and intent are measured, fit is not, and a number we invented would be worse than none.

None of the three calls a model on ShowPilot's side. They return figures and questions; you do the thinking. That is why they cost you nothing beyond a request and are not rate-limited any harder than a list call.

Drafting

draft_offer is the one tool that asks a model to compose something. You give it a brief:

Invite pricing-page visitors who came from our LinkedIn ads to the June security webinar. Ask for their email and company.

and it returns a whole offer ready for create_offer, plus three things worth reading before you send it:

rationale — what it set, in plain language
confirm — what a person must check: a campaign value it guessed, a date it inferred, a page path it assumed
unavailable — anything your brief asked for that this workspace does not have, and was therefore dropped

It is grounded in your own data: the sites you deploy on, the CRM values and account industries your visitors actually carry, your audiences by name. It will not invent a site you do not run on or a lifecycle stage you have never seen — it drops them and names them in unavailable.

It writes nothing, and a deployed draft always comes back switched off (deploy.live: false). You read it, then create or change the offer yourself. A model may compose; it does not get to publish by accident.

Because drafting runs a model on ShowPilot's side, it has its own small allowance — a few in a row, then a short wait — separate from the rate limit on everything else. When you hit it the error says how long to wait, and writing the offer by hand and sending it to create_offer always works.

What a connected client can see

A client gets the scopes your organization role carries — with one deliberate exception. conversations:transcripts, which lifts the identity masking on conversation content, is never granted to a connected client, including an organization admin's. Your assistant reads what visitors asked with the people masked. What your assistant can see explains what that looks like and how to lift it on purpose.

When a call fails

Every failure answers three things, not one:

{
  "error": "Someone changed this document since you read it.",
  "suggestion": "Read it again with get, re-apply your change on top of the new version, and send the new baseVersion.",
  "retryable": true
}

retryable means the same call, unchanged, could succeed later — a rate limit, a ShowPilot fault, or a 409 stale you can rebase onto. It is false where repeating would fail the same way: a missing permission, a plan that does not include the API, an id that does not exist, or input the operation does not accept. Read it before deciding whether to try again.

A typical session

whoami: confirms the organization, the role and what is permitted.
get tour: reads the tour as a document, including its version.
propose tour_spec with the edited document: findings come back by step ref.
apply tour_spec with the same document and the baseVersion from step 2.
execute publish_tour: freezes a revision for visitors.

One tool call costs one request against your rate limit, not two. Sign-in is cached for a minute, so revoking a client's access, or joining or leaving an organization, can take up to a minute to take effect on calls already in flight.

Every call goes through the same rules as the REST API: scopes, rate limits, idempotent writes and the sandbox when a test key is used.

The server publishes https://api.showpilot.com/.well-known/oauth-protected-resource, which names ShowPilot's authorization server. Clients register themselves there (dynamic registration or a client metadata document), run an OAuth 2.1 code flow with PKCE, and present the resulting bearer token. Tokens are short-lived; the client refreshes them without asking you again. Revoke a client's access from your account page at any time.

On this page