🤖 MCP Server Usage Guide¶

Connect any AI agent to Spector's search engine in minutes.

This guide covers practical setup for Claude Desktop, Cursor IDE, and custom MCP clients.

Quick Start (3 Steps)¶

1. Build the Distribution JAR¶

cd spector
mvn package -pl spector-dist -am -DskipTests

The fat JAR is produced at spector-dist/target/spector.jar.

2. Configure Your AI Agent¶

Add the following to your agent's MCP configuration (see per-agent sections below):

{
  "mcpServers": {
    "spector": {
      "command": "java",
      "args": [
        "--add-modules", "jdk.incubator.vector",
        "--enable-native-access=ALL-UNNAMED",
        "--enable-preview",
        "-jar", "/path/to/spector-dist/target/spector.jar",
        "--config", "/path/to/spector.yml"
      ]
    }
  }
}

3. Start Using¶

Your AI agent now has access to up to 21 tools. With cognitive memory enabled (spector.memory.enabled: true), all tools are registered. In SEARCH mode, only the 6 engine tools are available:

• "Search for documents about SIMD acceleration" → engine_search
• "Find articles mentioning 'Panama' and related to memory management" → engine_hybrid_search
• "What does the codebase say about quantization?" → engine_rag
• "Add this document to the index: ..." → engine_ingest
• "Remember that the user prefers dark mode" → memory_remember
• "What do you remember about the user's preferences?" → memory_recall

CLI Options¶

Configuration File¶

All settings can be specified in a spector.yml file:

spector:
  mode: HYBRID                   # SEARCH | MEMORY | HYBRID (default)
  engine:
    dimensions: 768
    capacity: 100000
    persistence-mode: DISK
    data-directory: .spector/index
  embedding:
    model: nomic-embed-text
    base-url: http://localhost:11434
  memory:
    enabled: true                  # Enable cognitive memory tools
    persistence-path: .spector/memory
    nodes-per-partition: 10000     # Records per semantic partition file

See the Configuration Guide for the complete list of settings.

Choosing Dimensions¶

The --dims flag must match your embedding model's output dimensionality:

Agent Configuration¶

Claude Desktop¶

Edit your claude_desktop_config.json:

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "spector": {
      "command": "java",
      "args": [
        "--add-modules", "jdk.incubator.vector",
        "--enable-native-access=ALL-UNNAMED",
        "--enable-preview",
        "-jar", "/absolute/path/to/spector.jar",
        "--config", "/absolute/path/to/spector.yml"
      ]
    }
  }
}

Cursor IDE¶

Add to your Cursor MCP settings (.cursor/mcp.json in your project, or global settings):

{
  "mcpServers": {
    "spector": {
      "command": "java",
      "args": [
        "--add-modules", "jdk.incubator.vector",
        "--enable-native-access=ALL-UNNAMED",
        "--enable-preview",
        "-jar", "/absolute/path/to/spector.jar",
        "--config", "/absolute/path/to/spector.yml"
      ]
    }
  }
}

Custom MCP Clients (Stdio)¶

Any application implementing the MCP client specification can connect to Spector. The stdio transport communicates via JSON-RPC 2.0 over stdio (stdin/stdout).

Key requirements:

1. Spawn the Java process with the correct JVM flags
2. Write JSON-RPC messages to the process's stdin
3. Read JSON-RPC responses from the process's stdout
4. All logging goes to stderr (stdout is reserved for protocol messages)

Example initialization sequence:

// Client → Server
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "my-app", "version": "1.0"}}}

// Server → Client
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-03-26", "capabilities": {"tools": {}}, "serverInfo": {"name": "spector-mcp", "version": "0.1.0"}}}

// Client → Server
{"jsonrpc": "2.0", "method": "notifications/initialized"}

Streamable HTTP Clients (Remote Agents)¶

When Spector runs as a server (via SpectorNode or Spector Enterprise), the same MCP tools are available over Streamable HTTP at the /mcp endpoint. This transport follows the MCP 2025-03-26 specification and is implemented by ArmeriaMcpTransport on the Armeria HTTP server.

Endpoint: http://localhost:7070/mcp

Modes:

• Stateless (default, recommended) — No Mcp-Session-Id header. Server restart doesn't break clients.
• Stateful — Mcp-Session-Id header for session tracking. Supports GET (SSE notifications) and DELETE (session teardown).

Example — initialize and call a tool:

# Step 1: Initialize
curl -X POST http://localhost:7070/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}'

# Step 2: Send initialized notification
curl -X POST http://localhost:7070/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# Step 3: Call a tool
curl -X POST http://localhost:7070/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"engine_status","arguments":{}}}'

MCP Tools Overview¶

Once connected, your agent has access to these tools:

Engine Tools (available in SEARCH and HYBRID mode)¶

Memory Tools (available in MEMORY and HYBRID mode)¶

Troubleshooting¶

Agent can't find or start the server¶

• Check the JAR path — Use absolute paths, not relative
• Check Java version — Spector requires JDK 25+. Run java -version to verify
• Check JVM flags — --add-modules jdk.incubator.vector is required

"Embedding provider not configured" errors¶

The engine_search and engine_rag tools require an embedding provider. Ensure:

1. Ollama is running: ollama serve
2. The model is pulled: ollama pull nomic-embed-text
3. Both --ollama-url and --ollama-model are specified in the args

Stdout corruption / garbled output¶

Spector redirects all logging to stderr. If you see garbled output:

• Check that nothing else is writing to stdout
• Verify the logback configuration routes to stderr
• Check for print statements in any custom code

Performance issues¶

• High latency on first query — The HNSW index is built lazily. First query triggers graph construction. Subsequent queries are fast.
• Memory usage — Vectors are stored off-heap. Monitor with -XX:NativeMemoryTracking=summary and jcmd <pid> VM.native_memory summary

Adding a New Tool¶

To extend the MCP server with a custom tool:

1. Create a new class extending McpToolHandler:

public final class MyCustomTool extends McpToolHandler {
    @Override public String name() { return "my_custom_tool"; }
    @Override public String description() { return "Does something useful."; }
    @Override public Map<String, Object> inputSchema() {
        return ToolSchemaBuilder.object()
                .requiredString("input", "The input parameter.")
                .build();
    }
    @Override public CallToolResult execute(SpectorEngine engine, Map<String, Object> args) {
        String input = requireString(args, "input");
        // Your logic here
        return textResult("Result: " + input);
    }
}

1. Register it in SpectorToolRegistry.handlers():

List.of(
    new EngineSearchTool(),
    // ... existing tools ...
    new MyCustomTool()  // ← add here
);

That's it — the tool is automatically available to all connected agents.

See Also¶

• MCP Integration Architecture — Module structure, data flow, and performance analysis
• Python SDK — Python client wrapping the MCP server
• Architecture Overview — Full system architecture
• REST API Reference — Alternative HTTP interface