Start the Server Manually

The first debugging step is always to start the MCP server directly and read the output. This isolates problems that would otherwise be invisible inside a client.

indexed mcp run

Healthy startup:

Indexed MCP server started
Transport: stdio
Collections available: my-docs, eng-tickets
Waiting for client connection...

Startup error examples:

Error: No collections found. Create one with 'indexed index create'.

→ You haven't indexed any documents yet. Run indexed index create files -c my-docs -p ./docs first.

Error: Configuration not found. Run 'indexed config init' first.

→ The workspace hasn't been initialized. Run indexed config init from the directory where you want .indexed/ (see Quick Start), then indexed init for models if needed.

Press Ctrl+C to stop the server once you've confirmed it starts.

Use the MCP Inspector

indexed mcp dev starts the MCP server with a built-in browser UI that lets you call search and search_collection directly, without involving any client:

indexed mcp dev

Indexed MCP dev server started
Opening MCP Inspector at http://127.0.0.1:5173

In the browser UI:

1. Select the search tool from the tool list
2. Enter a query value (e.g., "authentication guide")
3. Click Run

A successful call and response:

// Call
{ "query": "authentication guide" }

// Response
{
  "results": [
    {
      "collection": "my-docs",
      "document": "auth-setup.md",
      "chunk": "To configure SSO authentication, first set up your identity provider...",
      "score": 0.82
    }
  ]
}

If the call succeeds here but the client still doesn't work, the problem is in the client configuration — not in Indexed itself.

Check Your PATH

The most common failure mode for pipx installs is that the indexed binary is on a PATH that your client doesn't inherit. Verify the binary is findable:

which indexed
echo $PATH

Expected output of which indexed:

/Users/you/.local/bin/indexed

If which indexed returns nothing, the binary isn't on your PATH. Run pipx ensurepath and restart your shell, then try again.

If which indexed returns a path but your client still can't find it, use the full absolute path in your client config instead of "command": "indexed":

{
  "mcpServers": {
    "indexed": {
      "command": "/Users/you/.local/bin/indexed",
      "args": ["mcp", "run"]
    }
  }
}

Common Errors and Fixes

HTTP Transport Testing

If you're using the HTTP transport (e.g., for Docker or remote access), verify the server independently using curl before involving any client:

indexed mcp run --transport http --port 8000

In another terminal:

curl -s http://127.0.0.1:8000/tools | python3 -m json.tool

A working response lists the available tools:

{
  "tools": [
    { "name": "search", "description": "Search across all collections" },
    { "name": "search_collection", "description": "Search a specific collection" }
  ]
}

If curl fails but the server started without errors, check your firewall or that the port isn't already in use:

lsof -i :8000