haiku.rag/docs/mcp.md

Model Context Protocol (MCP)

The MCP server exposes haiku.rag as MCP tools for compatible MCP clients like Claude Desktop.

Starting MCP Server

The MCP server supports Streamable HTTP and stdio transports:

# Default streamable HTTP transport on 127.0.0.1:8001
haiku-rag mcp

# Custom port
haiku-rag mcp --port 9000

# Bind to all interfaces (e.g. inside a container)
haiku-rag mcp --host 0.0.0.0 --port 8001

# stdio transport (for Claude Desktop)
haiku-rag mcp --stdio

--host defaults to 127.0.0.1 (loopback only). Bind to 0.0.0.0 only when you want the MCP server reachable from outside the local machine — e.g. inside a Docker container with port mapping, or on a trusted LAN.

The server opens the database read-only. Ingestion goes through the CLI (haiku-rag add, add-src, delete) or haiku-ingester.

Collections

With several databases in lancedb.databases, the server covers all of them, as haiku-rag search does. Results, documents and citations name theirs in source. sources on the search and question tools restricts a call to a subset; source on get_document names the database holding the document. A name the server does not cover is an error. haiku-rag --db-name NAME mcp serves one. See Multiple Databases.

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "haiku-rag": {
      "command": "haiku-rag",
      "args": ["mcp", "--stdio"]
    }
  }
}

With a custom database path:

{
  "mcpServers": {
    "haiku-rag": {
      "command": "haiku-rag",
      "args": ["mcp", "--stdio", "--db", "/path/to/database.lancedb"]
    }
  }
}

After restarting Claude Desktop, you can ask Claude to search your documents or answer questions using your knowledge base.

Available Tools

Documents

• get_document - Retrieve a document by ID

  • document_id (required): The document ID
  • source (optional): The database holding it

• list_documents - List documents with pagination and filtering

  • limit (optional): Maximum number to return
  • offset (optional): Number to skip
  • filter (optional): SQL WHERE clause for filtering

Search

• search_documents - Search using hybrid search (vector + full-text)

  • query (required): Search query
  • limit (optional): Maximum results (uses config default if not specified)
  • include_images (optional, default true): Attach base64-encoded picture bytes to picture-labeled results
  • sources (optional): The databases to search

• search_documents_by_image - Search using an image as the query (registered only when the configured embedder supports images)

  • image_base64 (required): Base64-encoded image (PNG/JPEG bytes)
  • limit (optional): Maximum results
  • include_images (optional, default true)
  • sources (optional): The databases to search

Question Answering

• ask_question - Ask questions about your documents

  • question (required): The question to ask
  • cite (optional): Include source citations (default: false)
  • images_base64 (optional): Base64-encoded images attached to the question (requires a vision-capable QA model)
  • sources (optional): The databases to answer from

• analyze - Answer complex analytical questions via code execution

  • question (required): The question to answer
  • filter (optional): SQL WHERE clause to restrict document access
  • images_base64 (optional): Base64-encoded images attached to the question (requires a vision-capable analysis model)
  • sources (optional): The databases to analyze
  • Best for aggregation, computation, and multi-document analysis

Continuous ingestion

For continuous document ingestion (filesystem watch, S3 polling, HTTP sources, a job queue with retries), run haiku-ingester as a separate process against the same LanceDB.