MCP server.

The server lives at https://metasearch.sh/mcp. It speaks streamable HTTP, stateless, on protocol 2026-07-28 and the 2025 revisions before it. Tool calls go through the same validation, rate limits and ledger as POST /api/v1/search, so a search costs the same here as anywhere else.

Connect your assistant#

Give your assistant the URL and nothing else. The first time it calls a tool, it opens a metasearch.sh page in your browser where you sign in and approve it. Each host has its own steps:

Sign in and choose an organisation#

Approving an assistant takes three steps on metasearch.sh: sign in with the email link, pick the organisation that pays for its searches (the list shows only organisations where you can create keys, and is skipped when there is one), then allow access. The approval page names the assistant and the organisation, and shows the organisation's balance.

Behind the approval sits a connected-app key on that organisation. It has no secret you can copy, and it follows the same rules as any other key: spend caps, rate limits, the request log and the billing ledger. The assistant holds a short-lived access token and refreshes it on its own, so you sign in again only after about two months without use or after you revoke it.

Connected apps#

Every approved assistant is listed in the dashboard under Settings, Connected apps, with the organisation it charges and when it was last used. Revoke stops it at once: its next call gets HTTP 401 and it has to ask you again. Removing a member from an organisation revokes the assistants that member connected to it, and closing your account revokes them all.

A connected assistant reaches every mode, including X, TikTok, Instagram and YouTube posts and Reddit and Hacker News threads. One engine isn't available through assistant connections: asking for it by name returns an error that says so, and the router never picks it. A key from the dashboard reaches every engine.

With an API key#

For CI, headless agents and clients that cannot sign in, send an ms_live_ key from the dashboard as a bearer token instead. Put it in your shell profile:

$ export METASEARCH_API_KEY=ms_live_…

$ claude mcp add --transport http metasearch https://metasearch.sh/mcp \
  --header "Authorization: Bearer $METASEARCH_API_KEY"

{
  "mcpServers": {
    "metasearch": {
      "url": "https://metasearch.sh/mcp",
      "headers": {
        "Authorization": "Bearer ${env:METASEARCH_API_KEY}"
      }
    }
  }
}

[mcp_servers.metasearch]
url = "https://metasearch.sh/mcp"
bearer_token_env_var = "METASEARCH_API_KEY"

Each host page has its key variant too. A key and a sign-in can sit side by side: the server accepts either on every request.

Other clients#

Any client that supports remote MCP servers over HTTP works. Clients that follow the MCP authorization spec find the sign-in on their own: an unsigned tool call gets HTTP 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp. The server takes both client metadata documents and dynamic registration, so no client ID needs setting up. Listing the tools needs no sign-in.

Otherwise send Authorization: Bearer ms_live_…. A missing, unknown or revoked key gets HTTP 401; if the key cannot be checked during an outage, the answer is HTTP 503 with a Retry-After header.

Tools#

A result's id is its URL, so fetch can read any result straight from a search. Leave mode out and the server picks one from the query, then says which and why; see Routing. It never picks deep, and picks social only when the query names a platform (X, Twitter, TikTok, Instagram, YouTube), because those cost several times more: ask for them by name. In social, a named platform is searched alone; otherwise X and the one platform likeliest to hold the answer are searched together. One entry in providers is an engine preference; several are queried together and their results merged.

Both tools are read-only: they read public web pages and change nothing anywhere. Each returns a short text list for the model and the same results as structured content. The text ends with one line of billing:

Mode news (auto, model): Asked about recent events (p 0.97); used news with freshness week.
1. Solid-state batteries clear a manufacturing hurdle
   https://…
   Toyota and Idemitsu say their sulfide electrolyte line…
2. …
Charged $0.0015 · balance $0.9985

Pages from fetch start with a line marking them as untrusted web content. Treat that text as data: a page can contain instructions aimed at your agent.

What it costs#

Tools are priced exactly like the API: the engine's price for the call times 1.5, taken from the organisation's prepaid balance. A search starts at $0.00075 and a page fetch at $0.000375; empty and failed attempts cost nothing. Every engine and mode is on the pricing page. Owners and admins top up in the dashboard; an assistant never offers a top-up itself.