Integrations
MCP server
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
What is MCP, and why have one next to the API?
The Model Context Protocol is a small open standard that lets an AI client (Claude, an IDE agent, a chat assistant) call an application's capabilities directly. Think of it as "an API described in a way a language model can discover and use on its own".
The difference from the REST API is who is on the other end:
REST API (/api/v1) |
MCP (/mcp) |
|
|---|---|---|
| Caller | A program you wrote (a plugin, a script) | An AI client acting for a person |
| Knows what to call | Because you read these docs and coded it | Because the server describes its tools at runtime |
| Shape | Endpoints, parameters, JSON you parse | Named tools with typed inputs the model chooses between |
MCP is therefore not a replacement for the API: plugins and integrations
should keep using /api/v1. MCP exists so that a person can point their AI
assistant at their Searcio site and simply ask:
"What are people searching for on my shop that finds nothing?" "Do I actually sell anything matching 'vegan bag'?" "How much of my search quota is left this month?"
The AI discovers the available tools, calls them and answers. No one has to write integration code.
Endpoint
POST https://searcio.com/mcpAn MCP session is scoped to one connected site: the site whose credential authenticated it. It cannot reach any other site or account.
Authentication
MCP uses the site's dedicated read key, a read-only credential shown next to the write and search keys on the site page (Sites → your site → API keys). It can read the site's analytics and search its index, but it can never change the site or its data. You can give it to an AI client without risk; it grants no write access, which is exactly why it is separate from the write key.
Send it in either header:
Authorization: Bearer rk_live_abcX-Read-Key: rk_live_abcMost AI clients use Authorization: Bearer, so that is usually the form you
want. Requests are limited to 60 per minute. Rotating the site's keys issues a
new read key and invalidates the old one immediately.
| Status | When |
|---|---|
401 |
Missing or invalid read key (the write key is not accepted here) |
402 |
The account has no active plan (reason: no_active_plan) or an overdue payment (reason: payment_overdue) |
403 |
Site disabled, or the account is suspended (reason: account_suspended) |
Tools
All four tools are read-only: nothing exposed here can change the site or its data.
site-overview
The site's name, URL, status, platform, indexed document count and last sync,
plus the account's plan (is_free, upgrade_url) and whether the search engine
is reachable. No arguments.
plan-usage
The plan's quota against its limits: documents, searches this month and
connected sites, each with used, limit, percent and a near-limit flag. A null
limit means unlimited. No arguments.
search-analytics
What visitors actually search for:
| Argument | Default | Meaning |
|---|---|---|
days |
30 |
Period to analyse: 7, 30 or 90 |
limit |
10 |
Terms per list (1 to 50) |
The result includes total_searches, zero_result_rate_percent,
click_through_rate_percent, average_click_position, top_terms,
zero_result_terms (unmet demand) and rising_terms (growth compared with the
previous period).
Available only to accounts whose plan includes search analytics. Otherwise the tool returns an error result saying so, with the account's billing URL for an upgrade.
search-documents
Searches the site's own index, the way a visitor's search would.
| Argument | Default | Meaning |
|---|---|---|
query |
None | Required. What to search for |
type |
None | Restrict to one content type, e.g. product |
limit |
10 |
Results to return (1 to 25) |
It does not use the account's search quota and does not appear in the analytics: it is the owner inspecting their own index, not a visitor searching the storefront.
A useful sequence
The server's instructions steer the model toward this sequence, and it is worth knowing yourself:
search-analytics: find the searches that return nothing.search-documentson one of them: check whether the site really has nothing matching.- If it has something under different wording, that is a synonym problem, solved in the search settings. If it truly has nothing, that is missing content: a reason to add a product or a page.
The AI insights in the Searcio dashboard follow the same reasoning; MCP brings it into the customer's own AI client.
Connecting a client
Point any MCP-capable client at the endpoint with a bearer token. For example, in a Claude Desktop style configuration:
{
"mcpServers": {
"searcio": {
"type": "http",
"url": "https://searcio.com/mcp",
"headers": {
"Authorization": "Bearer rk_live_abc"
}
}
}
}To try the server by hand, the official MCP Inspector is the quickest check:
npx @modelcontextprotocol/inspectorChoose the Streamable HTTP transport, enter the endpoint URL and add the
Authorization header; without the header every call comes back 401.