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

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

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

Requires uteke-serve running. Uses Streamable HTTP transport:

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

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"
    }
  }
}

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"
    }
  }
}

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

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

Register uteke as an MCP server with the Hermes native client:

# 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

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

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.

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

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.

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 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).

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).

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.

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.

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.

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.

See also: Architecture — MCP Transport