MCP Server

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

The MCP server is read-only, whatever the key. Its tools search, list indexes and read stats and documents. An agent cannot create or delete an index, add or delete documents, or change settings through MCP. MCP lets an agent see what your indexes hold. It does not set search up for you. For that, give the agent the REST API or the CLI with an admin key, on a machine you control, and point it at llms.txt.

Setup

The MCP server is available at /api/mcp and speaks JSON-RPC 2.0 over HTTP, with no local proxy needed. Use a search key (hb_src_) unless the agent needs stats or single documents, which take an admin key (hb_adm_). See the tools below.

Claude Code

claude mcp add --transport http headband https://headband.dev/api/mcp \
  --header "Authorization: Bearer hb_src_YOUR_SEARCH_KEY"

By default the server is yours alone, in the current project. Add --scope project to write it to the project's .mcp.json instead, which is shared through git, so keep a key there only if everyone with the repository may use it. Run claude mcp get headband to check it.

Cursor (.cursor/mcp.json)

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

Other clients need the same two things: the URL, and an Authorization header with your 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, Elasticsearch or Visor.

A search key, the key most MCP client configs will hold, can call search_org, search_index and list_indexes. get_index_stats and get_document need an admin key, as their REST routes do. With a search key they answer an error result naming the key they need. Put an admin key only in a client that runs on your own machine or server, never in a browser.

Tool	Key	Arguments	What it does
`search_org`	search or admin	query (required), limit, perIndexLimit, filter, mode, indexAllowlist, indexDenylist, includeSources, branch	Search the indexes visible to the API key, at most 10 per call, merge results with reciprocal rank fusion, and return a single ranked list. Takes mode (instant or retrieval) for its Visor indexes. The query argument is query, not q as on /v1/search.
`search_index`	search or admin	index (required), q (required, empty lists every document), limit, filter, mode, branch	Full-text search a single index by UID. Returns ranked hits as JSON. Takes mode on a Visor index. There is no sort argument.
`list_indexes`	search or admin	branch	List every index the API key can access, with engine type.
`get_index_stats`	admin	index (required), branch	Get document count, indexing health, and field distribution for an index.
`get_document`	admin with documents.read	index (required), id (required), branch	Fetch a single document by its primary key.

search_org limits

search_org searches at most 10 indexes per call. With more, it searches the first 10 and lists the rest in skippedIndexes with the reason over_limit. The answer is still a success, so check skippedIndexes. To choose which indexes are searched, pass indexAllowlist (only these) or indexDenylist (never these, listed with the reason denylisted). An index that fails is listed there too, with its error, and the others still answer.

search_org result (shape)

{
  "query": "glacier mitts",
  "scope": "project",
  "results": [ ... ],
  "searchedIndexes": ["products", "articles", "..."],
  "skippedIndexes": [
    { "index": "faq", "reason": "over_limit" },
    { "index": "drafts", "reason": "denylisted" }
  ]
}

limit (the merged list) defaults to 10 and perIndexLimit to 5; both go up to 20. Each index that answers counts as one search on your plan.

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. The same key rules apply: with a search key the resource answers with stats null and no sample documents, and an admin key with documents.read gets both.