🤖 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 synapse/spector-cli -am -DskipTests

The standalone executable fat JAR is produced at synapse/spector-cli/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/synapse/spector-cli/target/spector.jar",
        "mcp",
        "--config", "/path/to/spector.yml"
      ]
    }
  }
}

3. Start Using¶

With cognitive memory enabled (spector.memory.enabled: true), your AI agent now has access to all 16 cognitive memory tools:

• "Remember that the user prefers dark mode" → memory_remember
• "What do you remember about the user's preferences?" → memory_recall
• "That answer was wrong — downgrade it" → memory_reinforce
• "Jot this down while I think it through" → memory_scratchpad
• "What do you actually know about this project?" → memory_introspect
• "Forget what I told you about the old API key" → memory_forget

CLI Options¶

Configuration File¶

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

spector:
  mode: MEMORY                   # Global mode (MEMORY)
  memory:
    enabled: true                  # Enable cognitive memory tools
    persistence-mode: DISK
    persistence-path: .spector/memory
    dimensions: 768
    nodes-per-partition: 10000     # Records per semantic partition file
  provider:
    embedding:
      model: nomic-embed-text
      base-url: http://localhost:11434

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":"memory_status","arguments":{}}}'

MCP Tools Overview¶

Once connected, your agent has access to Spector's 16 cognitive memory tools:

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 cognitive memory tools embed text to store and recall memories, so they 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:

import com.spectrayan.spector.mcp.tools.McpToolHandler;
import com.spectrayan.spector.mcp.schema.ToolSchemaBuilder;
import io.modelcontextprotocol.spec.McpSchema;
import java.util.Map;

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 McpSchema.CallToolResult execute(Map<String, Object> args) throws Exception {
        String input = requireString(args, "input");
        // Your custom logic using memory or search services
        return textResult("Result: " + input);
    }
}

1. Register it in SpectorToolRegistry:

import com.spectrayan.spector.mcp.tools.memory.MemoryRecallTool;

List.of(
    new MemoryRecallTool(memory),
    // ... 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