Zum Inhalt springen

Integrations

MCP server

https://searcio.com/api/v1

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/mcp

An 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:

http
Authorization: Bearer rk_live_abc
http
X-Read-Key: rk_live_abc

Most 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:

  1. search-analytics: find the searches that return nothing.
  2. search-documents on one of them: check whether the site really has nothing matching.
  3. 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:

json
{
  "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:

shell
npx @modelcontextprotocol/inspector

Choose the Streamable HTTP transport, enter the endpoint URL and add the Authorization header; without the header every call comes back 401.