MCP Server

ContextForge exposes a standalone FastMCP server. It is not spawned inside the Starlette worker lifecycle.

Quick Start

# stdio mode for local MCP clients
uv run --package contextunity-forge python -m contextunity.forge mcp

# HTTP/SSE mode on loopback, default port 8301
uv run --package contextunity-forge python -m contextunity.forge mcp --http

Cursor Configuration

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

Observability Tools

Tool	Backing RPC
`search_traces`	`AdminSearchTraces`
`get_trace_details`	`AdminGetTraceDetails`
`list_tenants`	`ListTenants`
`get_filter_options`	`AdminGetFilterOptions`
`get_analytics_summary`	`AdminGetAnalyticsSummary`
`get_system_analytics`	`AdminGetSystemAnalytics`
`get_cells`	`AdminGetCells`
`get_memory_layer_stats`	`AdminGetMemoryLayerStats`
`search_episodes`	`AdminSearchEpisodes`

Lab Tools

Group	Tools
DevTools	`run_ruff`, `run_tests`, `list_services`, `get_service_structure`, `get_service_fulldoc`
Docs	`search_docs`, `get_doc`, `list_docs`, `doc_stats`
Ingestion	`refresh_docs`, `check_staleness`, `cleanup_stale`

Architecture

MCP client
  -> FastMCP process
  -> BrainAdminClient gRPC wrappers / docs index / local subprocess devtools

Forge MCP does not query Brain’s PostgreSQL database directly.

Security

stdio trusts the local OS user.
HTTP/SSE binds to 127.0.0.1 by default and requires CU_FORGE_MCP_BEARER unless FORGE_MCP_INSECURE=1 is explicitly set.
Read-oriented observability tools require admin read access.
Action tools such as test/lint execution must not receive Brain write tokens.