Skip to Content
AeroSearch Docs
Quickstarts

MCP preview

MCP availability and a protocol preview for operator-managed test endpoints.

The public MCP endpoint and native client integration await WP-34. Grounded Answers await WP-27. The Cell search host does not currently serve /v1/mcp. This preview is not a working customer quickstart or a production daily check.

WP-34 must supply the public route, real key store, per-Collection Schema and client initialization/tool-discovery support. WP-27 must enable a real Answer tool before its acceptance check can pass.

Protocol preview

For an operator-managed test deployment only, set AEROSEARCH_MCP_URL to its explicit dedicated endpoint, AEROSEARCH_API_KEY to the configured search key, and AEROSEARCH_COLLECTION to the configured Collection. AEROSEARCH_BASE_URL is the Cell search host used by other quickstarts, not an MCP fallback. Supply AEROSEARCH_END_USER_TOKEN only when your server has minted a real token.

# generated-from-contract: contracts/openapi/v1.yaml
# MCP protocol preview; public availability waits for WP-34 and Answers for WP-27.
# Use the dedicated MCP endpoint supplied by your operator, not the Cell search URL.

import json
import os
import urllib.request

MCP_URL = os.environ.get("AEROSEARCH_MCP_URL")
if not MCP_URL:
    raise SystemExit("MCP not yet available: WP-34 must supply an explicit AEROSEARCH_MCP_URL")
API_KEY = os.environ.get("AEROSEARCH_API_KEY", "ask_YOUR_PROJECT_SEARCH_KEY")
COLLECTION = os.environ.get("AEROSEARCH_COLLECTION", "col_help")

def rpc(method, params, session_id, request_id):
    payload = {"jsonrpc": "2.0", "id": request_id, "method": method}
    if params is not None:
        payload["params"] = params
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
        "Authorization": f"Bearer {API_KEY}",
    }
    end_user_token = os.environ.get("AEROSEARCH_END_USER_TOKEN")
    if end_user_token:
        headers["X-AeroSearch-End-User-Token"] = end_user_token
    if session_id:
        headers["Mcp-Session-Id"] = session_id
    req = urllib.request.Request(
        MCP_URL, data=json.dumps(payload).encode(), method="POST", headers=headers
    )
    with urllib.request.urlopen(req) as res:
        assert res.status == 200
        envelope = json.loads(res.read().decode())
        if "error" in envelope:
            raise RuntimeError("MCP error: " + str(envelope["error"].get("code")))
        return envelope, res.headers.get("Mcp-Session-Id")

# initialize → tools/list → tools/call name=answer
result, session = rpc("initialize", {
    "protocolVersion": "2025-06-18", "capabilities": {},
    "clientInfo": {"name": "aerosearch-quickstart", "version": "1.0.0"},
}, None, 1)
assert "tools" in result["result"]["capabilities"]
listed, _ = rpc("tools/list", {"collection": COLLECTION}, session, 2)
assert any(tool["name"] == "answer" for tool in listed["result"]["tools"])
called, _ = rpc("tools/call", {"name": "answer", "arguments": {
    "collection": COLLECTION, "query": "reset password",
}}, session, 3)
assert not called["result"].get("isError", False)
print(json.dumps(called["result"]))

Verification status

The repository checks protocol bytes against a local double. It does not prove Claude Code/Cursor interoperability or a grounded Answer from a public Cell. Both remain open acceptance items for WP-34 and WP-27.

On this page