MCP Server

Torque includes a built-in Model Context Protocol (MCP) server, allowing AI assistants to search and manage your collections directly.

Overview

MCP is an open protocol by Anthropic that enables AI models to interact with external tools and data sources. Torque implements the Streamable HTTP transport (JSON-RPC 2.0 over HTTP POST), exposing nine tools for search, document management, and collection operations.

Protocol version: 2025-11-25

Quick Start

Example: Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "torque": {
      "url": "http://localhost:8108/api/mcp",
      "headers": {
        "X-TYPESENSE-API-KEY": "your-api-key"
      }
    }
  }
}

Replace your-api-key with the API key shown in the server startup banner. Once configured, Claude can search your collections, explore schemas, manage documents, and create collections.

Any MCP Client

Any MCP-compatible client can connect using the Streamable HTTP transport. The endpoint URL is http://<host>:8108/api/mcp and requires the same API key authentication as the HTTP API.

Authentication

The MCP endpoint uses the same API key authentication as all other endpoints. Pass the key via:

• X-TYPESENSE-API-KEY: ... header (recommended)
• Authorization: Bearer ... header

Scoped API keys are supported — a search-only key can use read tools but will receive 403 Forbidden on write operations.

Available Tools

Tool Details

search

Search a collection with the full Torque search API: text queries, filters, facets, sorting, grouping, and typo tolerance.

{
  "name": "search",
  "arguments": {
    "collection": "products",
    "q": "laptop",
    "query_by": "title,description",
    "filter_by": "price:>100 && brand:=Acme",
    "sort_by": "price:desc",
    "facet_by": "brand",
    "per_page": 20
  }
}

Returns the standard Torque search response: found, hits with documents and highlights, facet_counts, and search_time_us.

multi_search

Run multiple searches in a single request. Each item in the searches array is an independent search with its own collection, query, and parameters.

{
  "name": "multi_search",
  "arguments": {
    "searches": [
      {"collection": "products", "q": "laptop", "query_by": "title"},
      {"collection": "articles", "q": "review", "query_by": "body"}
    ]
  }
}

collections

Discover what collections exist on the server.

{
  "name": "collections",
  "arguments": {}
}

schema

Inspect a collection's field schema to understand available fields, types, and attributes before searching.

{
  "name": "schema",
  "arguments": {"collection": "products"}
}

get_document

Retrieve a specific document by ID.

{
  "name": "get_document",
  "arguments": {"collection": "products", "id": "42"}
}

create_collection

Create a collection with typed fields.

{
  "name": "create_collection",
  "arguments": {
    "name": "products",
    "fields": [
      {"name": "title", "type": "string"},
      {"name": "price", "type": "float", "sort": true},
      {"name": "brand", "type": "string", "facet": true}
    ]
  }
}

upsert_document

Insert a new document or replace an existing one with the same ID.

{
  "name": "upsert_document",
  "arguments": {
    "collection": "products",
    "document": {
      "id": "1",
      "title": "Laptop Pro 16",
      "price": 1299.99,
      "brand": "Acme"
    }
  }
}

delete_document

{
  "name": "delete_document",
  "arguments": {"collection": "products", "id": "1"}
}

delete_collection

Delete a collection and all its data. Enabled by default; can be disabled with allow_drop_collection = false in config.

{
  "name": "delete_collection",
  "arguments": {"collection": "products"}
}

Protocol Reference

Initialize

The MCP handshake must be the first message. The server responds with its capabilities and version.

POST /api/mcp
Content-Type: application/json
X-TYPESENSE-API-KEY: your-key

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "my-app", "version": "1.0"}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {"tools": {}},
    "serverInfo": {"name": "torque", "version": "0.5.0"}
  }
}

List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Call a Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "collection": "products",
      "q": "laptop",
      "query_by": "title"
    }
  }
}

Successful tool results:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "{\"found\": 2, \"hits\": [...]}"}]
  }
}

Tool errors (collection not found, invalid query, etc.):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "Collection 'foo' not found"}],
    "isError": true
  }
}

Ping

{"jsonrpc": "2.0", "id": 4, "method": "ping", "params": {}}

Notifications

Notifications (e.g. notifications/initialized) return 202 Accepted with no body, per the MCP spec.

Transport Details

Error Codes

Standard JSON-RPC 2.0 error codes:

Tool-level errors (collection not found, document not found, invalid schema, etc.) are returned as successful JSON-RPC responses with isError: true in the result, following the MCP convention.