MCP Server

Headband exposes an MCP (Model Context Protocol) server over HTTP. Connect Claude Desktop, Cursor, or any MCP client to give your AI assistant direct access to your search indexes. Auth uses the same API keys as the REST API.

Setup

The MCP server is available at /api/mcp and speaks JSON-RPC 2.0 over HTTP — no local proxy needed. Add this to your MCP client config:

Claude Desktop / Cursor config

{
  "mcpServers": {
    "headband": {
      "url": "https://headband.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer hb_your_api_key"
      }
    }
  }
}

GET/api/mcp

Returns MCP server capability descriptor.

Auth admin or search keyReturns 200

Response

{
  "name": "headband",
  "transport": "http",
  "protocol": "json-rpc-2.0",
  "mcpProtocolVersion": "2025-06-18",
  "hint": "POST a JSON-RPC 2.0 request with Authorization: Bearer hb_<key>"
}

Available Tools

The MCP server exposes 5 tools. All are engine-agnostic — the AI assistant never needs to know whether an index is backed by Meilisearch, Typesense, or Elasticsearch.

search_orgSearch across all indexes visible to the API key, merge results with reciprocal rank fusion, and return a single ranked list

search_indexFull-text search a single index by UID. Returns ranked hits as JSON

list_indexesList every index the API key can access, with engine type

get_index_statsGet document count, indexing health, and field distribution for an index

get_documentFetch a single document by its primary key

Resources

Each index is exposed as an MCP resource at headband://index/{uid}. Reading a resource returns index stats and a sample of documents — useful for letting an AI assistant understand the shape of your data before searching.