🤖 MCP Integration Architecture¶

Spector's built-in Model Context Protocol (MCP) server gives any AI agent instant, in-process access to SIMD-accelerated cognitive memory — with zero network overhead.

Overview¶

The Model Context Protocol (MCP) is Anthropic's open standard for connecting AI agents to external data sources. Instead of writing custom glue-code with orchestration frameworks, agents connect directly to an MCP server via JSON-RPC and autonomously invoke tools.

Spector's MCP server runs in-process. When Claude Desktop or Cursor calls memory_recall, the request goes from JSON-RPC → Java method call → SIMD kernel — never touching a network socket. This makes Spector 23–113× faster than Python-based MCP servers that route through HTTP/gRPC.

Spector supports two MCP transports:

• Stdio — JSON-RPC 2.0 over stdin/stdout, for CLI agents (Claude Desktop, Cursor)
• Streamable HTTP — JSON-RPC 2.0 over HTTP at /mcp, for remote/web agents (MCP 2025-03-26 spec)

Architecture¶

graph LR
    subgraph "AI Agent (Claude, Cursor, etc.)"
        Agent["\ud83e\udd16 AI Agent"]
    end

    subgraph "spector-mcp (in-process)"
        StdioTransport["\ud83d\udce1 StdioTransport<br/><i>JSON-RPC 2.0 — stdin/stdout</i>"]
        HttpTransport["\ud83c\udf10 ArmeriaMcpTransport<br/><i>Streamable HTTP — POST/GET/DELETE /mcp</i>"]
        Server["\u26a1 SpectorMcpServer<br/><i>Thin orchestrator</i>"]

        subgraph Providers
            TR["\ud83d\udd27 SpectorToolRegistry"]
            RP["\ud83d\udcc4 SpectorResourceProvider"]
            PP["\ud83d\udcac SpectorPromptProvider"]
        end

        subgraph "Cognitive Memory Tools — 16"
            M1["MemoryRememberTool"]
            M2["MemoryRecallTool"]
            M3["MemoryForgetTool"]
            M4["MemoryIntrospectTool"]
            M5["... 12 more"]
        end

        subgraph Foundation
            SB["ToolSchemaBuilder"]
            RF["ResultFormatter"]
            TH["McpToolHandler<br/><i>Abstract base</i>"]
        end
    end

    subgraph "spector-memory"
        Memory["🧠 SpectorMemory"]
    end

    subgraph "spector-core"
        SIMD["🔬 SIMD Kernels<br/><i>AVX2/AVX-512/NEON</i>"]
    end

    Agent -- "stdin/stdout" --> StdioTransport
    Agent -- "HTTP POST /mcp" --> HttpTransport
    StdioTransport --> Server
    HttpTransport --> Server
    Server --> TR & RP & PP
    TR --> M1 & M2 & M3 & M4 & M5
    M1 & M2 & M3 & M4 & M5 --> TH
    M1 & M2 & M3 & M4 & M5 --> SB
    M1 & M2 & M3 & M4 & M5 --> RF
    M1 & M2 & M3 & M4 & M5 --> Memory
    Memory --> SIMD

Data Flow¶

sequenceDiagram
    participant Agent as 🤖 AI Agent
    participant MCP as 📡 MCP Transport (stdio / Streamable HTTP)
    participant Handler as 🔧 McpToolHandler
    participant Memory as 🧠 SpectorMemory
    participant SIMD as 🔬 SIMD Kernel

    Agent->>MCP: tools/call {"name": "memory_recall", "arguments": {"query": "..."}}
    MCP->>Handler: MemoryRecallTool.execute(args)

    Note over Handler: requireString(args, "query")<br/>optionalInt(args, "top_k", 5)

    Handler->>Memory: memory.recall(query, topK)
    Memory->>SIMD: Fused scoring: sim × importance × decay (off-heap MemorySegment)
    SIMD-->>Memory: ScoredMemory[] (ultra-fast)
    Memory-->>Handler: RecallResult
    Handler-->>MCP: CallToolResult (JSON-RPC)
    MCP-->>Agent: tools/call response

Module Structure¶

spector-mcp/src/main/java/com/spectrayan/spector/mcp/
├── SpectorMcpServer.java          ← Thin orchestrator (assembly only)
├── SpectorMcpMain.java            ← CLI entry point
├── schema/
│   └── ToolSchemaBuilder.java     ← Type-safe fluent builder for JSON schemas
├── tools/
│   ├── McpToolHandler.java        ← Abstract base with timing, error handling
│   ├── SpectorToolRegistry.java   ← Tool discovery & registration
│   └── memory/                    ← 16 cognitive memory tools
│       ├── MemoryToolHandler.java     ← Memory-aware base handler
│       ├── MemoryRememberTool.java
│       ├── MemoryRecallTool.java
│       ├── MemoryScratchpadTool.java
│       ├── MemoryReinforceTool.java
│       ├── MemoryForgetTool.java
│       ├── MemoryStatusTool.java
│       ├── MemoryIntrospectTool.java
│       ├── MemorySuppressTool.java
│       ├── MemoryResolveTool.java
│       ├── MemoryReminderTool.java
│       ├── MemoryWhyNotTool.java
│       ├── MemoryComputeImportanceTool.java
│       ├── MemoryInspectTool.java
│       ├── MemoryExportTool.java
│       ├── MemoryBrowseTool.java
│       └── MemorySalienceTool.java
├── resources/
│   └── SpectorResourceProvider.java   ← Resource definitions & handlers
├── prompts/
│   └── SpectorPromptProvider.java     ← Prompt templates & handlers
└── util/
    └── ResultFormatter.java           ← Search result formatting utilities

Tool Reference¶

The MCP server exposes 16 cognitive memory tools. All are registered when cognitive memory is enabled (spector.memory.enabled: true). Memory tools embed text to store and recall memories, so an embedding provider (e.g., Ollama) must be configured.

Extending the MCP Server¶

Adding a New Tool¶

Every tool extends McpToolHandler, which handles timing, error handling, and argument parsing. You implement four methods:

public abstract class McpToolHandler {
    abstract String name();
    abstract String description();
    abstract Map<String, Object> inputSchema();
    abstract CallToolResult execute(Map<String, Object> args);

    // Base class automatically provides:
    // - Timing wrapper (nanoTime → milliseconds)
    // - Structured error handling with logging
    // - Argument parsing: requireString(), optionalInt(), optionalString()
    // - Result factories: textResult(), errorResult()
}

Define the tool schema with ToolSchemaBuilder:

var schema = ToolSchemaBuilder.object()
    .requiredString("query", "Natural language query for memory recall.")
    .optionalInt("top_k", "Number of results to return.", 5)
    .optionalString("profile", "Cognitive scoring profile preset.", "")
    .build();

Register the tool in SpectorToolRegistry.handlers() — one line per tool:

handlers.add(new MemoryRememberTool(memory));
handlers.add(new MemoryRecallTool(memory));
// ... 14 more cognitive memory tools
// handlers.add(new YourNewTool(memory));  ← just add here

Performance: Why In-Process Wins¶

The Python MCP Tax¶

Python MCP servers introduce multiple layers of overhead:

graph LR
    A1["🤖 Agent"] --> B1["JSON-RPC"]
    B1 --> C1["🐍 Python process"]
    C1 --> D1["Deserialize"]
    D1 --> E1["HTTP/gRPC round-trip"]
    E1 --> F1["Vector DB"]
    F1 --> G1["Serialize response"]
    G1 --> H1["JSON-RPC"]
    H1 --> I1["🤖 Agent"]

    style C1 fill:#e74c3c,color:white
    style E1 fill:#e74c3c,color:white

Total: 2–10ms per query (network + GIL + serialization)

Spector's Zero-Copy Path¶

graph LR
    A2["🤖 Agent"] --> B2["JSON-RPC"]
    B2 --> C2["☕ Virtual Thread"]
    C2 --> D2["SpectorMemory.recall()"]
    D2 --> E2["Off-heap MemorySegment"]
    E2 --> F2["SIMD registers"]
    F2 --> G2["✅ Results"]

    style C2 fill:#00b894,color:white
    style E2 fill:#00b894,color:white
    style G2 fill:#00b894,color:white

Total: 88µs p50 per query (23–113× faster)

Security Considerations¶

See Also¶

• MCP Server Usage Guide — Practical setup for Claude Desktop, Cursor, and custom agents
• Architecture Overview — Full system architecture
• Core Concepts — HNSW, BM25, RRF deep-dives