MCP Server (Model Context Protocol)

August 5, 2026 · View on GitHub

Expose uteke memories as tools to AI coding agents — Claude Code, Claude Desktop, Cursor, Copilot, and any MCP-compatible client.

Quick Start

Option A: Stdio Transport (recommended for local agents)

No daemon needed — uteke-mcp communicates over stdin/stdout:

// Claude Code — .mcp.json or ~/.claude/settings.json
{
  "mcpServers": {
    "uteke": {
      "command": "uteke-mcp"
    }
  }
}

Option B: HTTP Transport (for remote/shared access)

Requires uteke-serve running. Uses Streamable HTTP transport:

{
  "mcpServers": {
    "uteke": {
      "url": "http://127.0.0.1:8767/mcp"
    }
  }
}

Client Configuration

Claude Code

Create or edit .mcp.json in your project root, or ~/.claude/settings.json for global access:

// Stdio (recommended)
{
  "mcpServers": {
    "uteke": {
      "command": "uteke-mcp"
    }
  }
}

// HTTP (requires uteke-serve)
{
  "mcpServers": {
    "uteke": {
      "url": "http://127.0.0.1:8767/mcp"
    }
  }
}

Claude Desktop

Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "uteke": {
      "command": "uteke-mcp"
    }
  }
}

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "uteke": {
      "command": "uteke-mcp"
    }
  }
}

Hermes

# Stdio transport
hermes mcp add uteke --command uteke-mcp

# HTTP transport (requires uteke-serve running)
hermes mcp add uteke --url http://127.0.0.1:8767/mcp

MCP is Tool-Based (Not Automatic)

The MCP server exposes uteke as tools — the agent decides when to call uteke_recall, uteke_remember, etc. This means:

✅ On-demand: The agent calls memory tools only when needed (e.g., "recall project context before coding")
✅ Agent-controlled: The agent decides what to store and when to query
❌ No auto recall: Memories are NOT automatically injected every turn
❌ No auto extract: Facts are NOT automatically extracted from conversations

If you need automatic recall (memories injected every LLM call without the agent asking), use Mode C (shell hook) instead:

uteke init --agent hermes  # Installs pre_llm_call hook

Which Integration Mode to Use?

Need	Use This	How
On-demand memory, coding agents	MCP (this page)	`uteke-mcp` or `POST /mcp`
Automatic recall every turn	Mode C (shell hook)	`uteke init --agent hermes`
Automatic recall + auto extract	~~Mode B (memory-provider)~~	❌ Deprecated (removed 2026-06-29)
Multi-agent shared rooms	MCP + Mode C combo	Mode C for auto recall, MCP for room operations

Tip: MCP and Mode C work great together. Use Mode C for automatic recall on every LLM call, and MCP for explicit tool-based operations like uteke_doc_create, uteke_graph, or uteke_room_recall.

Available Tools

Both transports expose the same 35 tools (MCP protocol version 2025-06-18):

Tool	Description
`uteke_remember`	Store a memory (supports type, room, author, tags)
`uteke_recall`	Semantic search (supports tags filter, min_score)
`uteke_search`	Text search with optional tag filter
`uteke_list`	List memories (supports pagination via offset)
`uteke_forget`	Delete a memory
`uteke_stats`	Memory store statistics
`uteke_context`	AI-optimized context output for prompts
`uteke_dream`	One-command maintenance pipeline (lint → backlinks → dedup → orphans)
`uteke_doc_create`	Create a document (wiki/knowledge base entry)
`uteke_doc_get`	Retrieve a document by ID
`uteke_doc_list`	List all documents
`uteke_doc_search`	Search documents
`uteke_doc_delete`	Delete a document
`uteke_doc_update`	Partial document update with chunk rebuild (#589)
`uteke_doc_move`	Move document to new parent (#438)
`uteke_graph`	Get nodes + edges JSON for visualization
`uteke_graph_add_edge`	Create a typed edge between two memories (#542)
`uteke_graph_remove_edge`	Remove an edge between two memories (#542)
`uteke_room_recall`	Semantic recall within a room
`uteke_room_memories`	List memories in a room (#569)
`uteke_room_create`	Create a room
`uteke_room_delete`	Delete a room
`uteke_room_stats`	Room statistics
`uteke_room_summary`	Room topic summary (tag clustering, no LLM)
`uteke_room_summary_document`	Generate summary document from room (→ `POST /room/summary-document`)
`uteke_room_add_document`	Link an existing document to a room (#859)
`uteke_room_remove_document`	Unlink a document from a room (#859)
`uteke_room_list_documents`	List documents linked to a room (#859)
`uteke_doc_list_rooms`	List rooms that reference a document (#859)
`uteke_tags_list`	List all tags with counts (#566)
`uteke_tags_rename`	Rename a tag across all memories (#566)
`uteke_tags_delete`	Delete a tag from all memories (#566)
`uteke_pin`	Pin a memory (prevent decay) (#566)
`uteke_unpin`	Unpin a memory (#566)

Transport Comparison

	Stdio	HTTP
Binary	`uteke-mcp`	`uteke-serve`
Daemon needed	No	Yes
Remote access	No	Yes
Protocol	JSON-RPC over stdin/stdout	Streamable HTTP (POST `/mcp`)
Best for	Local agents, single machine	Shared/team, remote access

Tip: HTTP transport is recommended when uteke-serve is already running — it avoids subprocess overhead and works across machines. Stdio transport is simpler for local, single-agent setups where no daemon is desired.

Remote Access (VPS / Server / Domain)

Connect from a local agent to a remote uteke-serve

When uteke-serve runs on a VPS or remote server, your local MCP client connects over HTTP:

# On the server — start uteke-serve with auth enabled
UTEKE_AUTH_TOKEN=your-secret uteke-serve --host 0.0.0.0 --port 8767

Note: In production, use environment variables for tokens — never commit secrets to config files. Some clients support env var substitution (e.g., $UTEKE_AUTH_TOKEN).

// Claude Code — .mcp.json
{
  "mcpServers": {
    "uteke": {
      "url": "https://uteke.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret"
      }
    }
  }
}

// Claude Desktop
{
  "mcpServers": {
    "uteke": {
      "url": "https://uteke.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret"
      }
    }
  }
}

// Cursor
{
  "mcpServers": {
    "uteke": {
      "url": "https://uteke.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret"
      }
    }
  }
}

Docker on a VPS

docker run -d --name uteke \
  -p 8767:8767 \
  -e UTEKE_AUTH_TOKEN=your-secret \
  -v uteke-data:/data \
  ghcr.io/codecoradev/uteke:latest

Point your MCP client at http://YOUR_VPS_IP:8767/mcp (or use a domain with TLS — see below).

Domain + TLS (Recommended for Production)

For HTTPS with a domain, use a reverse proxy (Caddy, Nginx, or Cloudflare Tunnel) in front of uteke-serve:

# uteke-serve still on localhost — the proxy handles TLS
UTEKE_AUTH_TOKEN=your-secret uteke-serve --host 127.0.0.1 --port 8767

See TLS & Reverse Proxy for full setup guides (Caddy, Nginx, Cloudflare Tunnel).

Important: Network Security

Setting	Value	Why
`--host`	`127.0.0.1` (local) or `0.0.0.0` (remote)	Bind to localhost unless you need remote access
`UTEKE_AUTH_TOKEN`	Set a strong token	Required for remote access — without it, anyone can read/write your memories
TLS	Use reverse proxy + HTTPS	Encrypts traffic in transit — strongly recommended for remote setups
Firewall	Allow only port 8767/tcp	Restrict access at the network level

The MCP server uses the default namespace by default. Each agent can use its own isolated namespace by passing a namespace argument to any tool call. Memories in one namespace are never visible to another.

This is the MCP equivalent of the CLI's --namespace flag — see Multi-Agent Isolation for details.

JSON-RPC 2.0 Compliance (#573/#576)

The MCP server implements strict JSON-RPC 2.0 compliance (v0.6.7):

Tagged union responses: The result field uses a tagged union ({"type": "result", "content": [...]}) per the MCP spec, not a bare array.
No notification response: JSON-RPC notifications (requests without id) receive no response body, as required by the spec. This fixes Claude Code connectivity issues where unexpected responses on notifications caused handshake failures.
Claude Code compatible: Tested and verified with Claude Code, Claude Desktop, Cursor, and Hermes MCP client.

Memory-Provider Integration (#575/#577)

For automatic recall (memories injected every LLM call without the agent asking), use the --memory-provider flag with uteke init:

# pi (pi.dev)
uteke init --agent pi --memory-provider

# Claude Code
uteke init --agent claude --memory-provider

# Cursor
uteke init --agent cursor --memory-provider

This installs uteke as the agent's default memory provider — relevant memories are recalled and injected automatically every turn. No MCP server needed; talks to the uteke binary directly.

Note: The --memory-provider flag is only deprecated for Hermes (removed 2026-06-29). For pi, Claude Code, and Cursor, it is the recommended integration mode.

Docker

When running uteke in Docker, both transports are available:

HTTP: Start the container normally — the MCP endpoint is at http://localhost:8767/mcp via port mapping.
Stdio: Use --entrypoint uteke-mcp to run the MCP binary directly inside the container.

See Docker guide — MCP for full Docker-specific configuration and examples.

Troubleshooting

Problem	Solution
`uteke-mcp: command not found`	Run `install.sh` or `cargo install -p uteke-mcp` to install the binary
`Permission denied`	`chmod +x $(which uteke-mcp)` or ensure the binary is on your `PATH`
`Connection refused` (HTTP)	Ensure `uteke-serve` is running: `uteke-serve`
Client can't see tools	Verify the MCP config JSON is valid and the client has been restarted
Slow first query	The embedding model (~188MB) downloads on first use — subsequent calls are ~30ms

See also: Architecture — MCP Transport