MCP Server

The ContextView MCP Server exposes 7 admin tools via the Model Context Protocol. AI assistants (Cursor, Claude Desktop, etc.) can query traces, browse memory, and manage agents through natural language.

Quick Start

# stdio mode (Cursor, Claude Desktop)
uv run python -m contextunity.view.mcp.server

# SSE mode (web clients, multi-user)
uv run python -m contextunity.view.mcp.server --sse --port 8301

Cursor Configuration

{
  "mcpServers": {
    "contextunity": {
      "command": "uv",
      "args": ["run", "python", "-m", "contextunity.view.mcp.server"]
    }
  }
}

Available Tools

Tool	Description	Returns
`get_recent_traces`	Recent agent execution traces	`list[TraceRow]`
`get_trace_stats`	Trace statistics per tenant	`TraceStats`
`get_episode_stats`	Episode/memory statistics	`EpisodeStats`
`get_recent_episodes`	Recent memory episodes	`list[EpisodeRow]`
`list_agents`	List all agent configurations	`list[AgentRow]`
`get_agent_detail`	Get agent config by ID	`AgentRow`
`brain_search`	Semantic search in Brain	`list[SearchResult]`

Architecture

AI Assistant (Cursor/Claude)
        │
        │  MCP (stdio or SSE)
        ▼
┌──────────────┐
│  FastMCP     │
│  Server      │
├──────────────┤
│  brain_db    │ ← Direct PostgreSQL queries
│  queries     │   (same data layer as Dashboard)
└──────────────┘

The MCP server uses the same brain_db data layer as the Dashboard — typed Pydantic schemas (TraceRow, EpisodeRow, etc.) ensure consistent data formats across both interfaces.

Tool Details

`get_recent_traces`

Returns the most recent agent execution traces, optionally filtered by tenant or time range.

`get_trace_stats`

Aggregated trace statistics — total executions, error rates, average latency, token usage per tenant.

`brain_search`

Semantic vector search against the Brain knowledge store. Returns matching documents with relevance scores and metadata.

> brain_search("how does the product matching work?")
[
  { content: "The Matcher uses hybrid trigram...", score: 0.87, ... },
  { content: "Product normalization pipeline...", score: 0.82, ... }
]

Data Schemas

All tools return typed results defined in data/brain_db/schemas.py:

class TraceRow(TypedDict):
    trace_id: str
    agent_id: str
    tenant_id: str
    status: str
    started_at: str
    duration_ms: float
    total_tokens: int

class EpisodeRow(TypedDict):
    episode_id: str
    session_id: str
    content: str
    created_at: str

class SearchResult(TypedDict):
    content: str
    score: float
    metadata: NotRequired[dict[str, Any]]

Security

The MCP server inherits the same ContextToken-based authorization as the gRPC AdminService:

Read tools → require admin:read permission
Write tools → require admin:write permission
Tenant isolation is enforced at the query level