search)

This page shows how to call the search backend from AgentRouter using the MCP Streamable HTTP protocol. The traditional REST APIs remain available; MCP is an additional surface.

Endpoint & Auth

Endpoint: POST /v1/mcp/search
Headers:
- Content-Type: application/json
- Accept: application/json or text/event-stream (to stream)
- MCP-Protocol-Version: 2025-06-18 (optional; falls back to 2025-03-26)
Auth: Authorization: Bearer sk-ar-... or x-api-key. Signed-in sessions are also accepted.
CORS: all origins are allowed for easier agent access.

JSON-RPC Methods

Method	Purpose
`initialize`	Returns protocol version and capabilities (streaming supported).
`tools/list`	Returns the `search` tool with metadata and schema.
`tools/call`	Invokes the `search` tool.

Tool Metadata

{
  "name": "search",
  "description": "Call search and return ranked snippets.",
  "metadata": {
    "category": "web",
    "version": "1.0",
    "docsUrl": "/docs/integration/mcp-search",
    "maintainer": "search-team",
    "tags": ["search", "mcp"]
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "minLength": 1 },
      "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 },
      "top_n": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Preferred over limit" },
      "category": { "type": "string", "description": "Optional" }
    },
    "required": ["query"]
  }
}

Examples

pydantic-ai

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

server = MCPServerStreamableHTTP(
    "https://your-agentrouter.com/v1/mcp/search",
    api_key="sk-ar-your-key"
)
agent = Agent("gateway/openai:gpt-5", toolsets=[server])

result = await agent.run("Find news about AgentRouter")
print(result.output)

cURL (non-streaming)

curl -X POST https://your-agentrouter.com/v1/mcp/search \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":"1",
    "method":"tools/call",
    "params":{
      "name":"search",
      "arguments":{
        "query":"agent router",
        "top_n":5,
        "category":"web"
      }
    }
  }'

Streaming (SSE)

Set Accept: text/event-stream or append ?stream=1. Events arrive as progress then final result:

event: progress
data: {"jsonrpc":"2.0","id":"1","result":{"content":[...]}}

event: result
data: {"jsonrpc":"2.0","id":"1","result":{"content":[...],"meta":{"took_ms":12,"total":8}}}

Parameters

query (required): search query string.
top_n: number of results to return (preferred over limit).
limit: result count, 1–20, default 8.
category: category passthrough.

Errors & Status Codes

400: JSON parse or param validation failed (-32600 / -32602).
401: missing/invalid API key (-32001).
404: unknown method/tool (-32601).
402: insufficient balance when billing is enabled.
503: feature flag disabled.

MCP Search

On this page