MCP integration

Custom (stdio + HTTP)

Embed prom.codes into your own MCP host or agent runtime. Covers stdio launch and the planned HTTP transport.

If you build your own agent runtime (Claude Code, OpenHands, an in-house CLI, …), prom.codes speaks plain stdio MCP and — from Phase 3 onward — HTTP/SSE for remote-only setups. New here? Read the two-server overview first — it explains how the context engine and the memory server work together and what each environment variable does.

stdio (works today)

prom.codes ships its everyday pair as stdio MCP servers, and most hosts spawn both: the context engine (binary prometheus-context-mcp, @prom.codes/context-mcp) and the agent-memory server (binary prometheus-memory-mcp, @prom.codes/memory-mcp). They take the same PROMETHEUS_API_KEY, so they hash to the same project identity and agree on which project they are serving. The workspace root is auto-detected (MCP roots capability, or CLAUDE_PROJECT_DIR under Claude Code); set PROMETHEUS_WORKSPACE_ROOT only to point at a different folder. A third, optional server — the token saver (@prom.codes/saver) — is a pure-JS installer that needs no key; spawn it the same way if you want it. Spawn each as a child process and pipe MCP JSON-RPC over its stdin/stdout:

import { spawn } from "node:child_process";

const childEnv = {
  ...process.env,
  PROMETHEUS_API_KEY: process.env.PROMETHEUS_API_KEY!,
};

// Context engine.
const context = spawn("npx", ["-y", "@prom.codes/context-mcp@latest"], {
  env: childEnv,
  stdio: ["pipe", "pipe", "inherit"],
});

// Agent memory, alongside.
const memory = spawn("npx", ["-y", "@prom.codes/memory-mcp@latest"], {
  env: childEnv,
  stdio: ["pipe", "pipe", "inherit"],
});

// Optional: the token saver. Pure JS, no key required. Run its `setup`
// tool once per workspace.
const saver = spawn("npx", ["-y", "@prom.codes/saver@latest"], {
  env: process.env,
  stdio: ["pipe", "pipe", "inherit"],
});

// Wire each child's stdin/stdout into its own MCP client transport.

Any compliant MCP client transport works. The reference Node SDK uses StdioClientTransport from @modelcontextprotocol/sdk — one transport per child. For what each variable means, see the configuration reference; for the memory tool surface see Agent Memory.

Environment variables — context server

Variable	Required	Default	Purpose
`PROMETHEUS_API_KEY`	yes	—	Tenant-scoped bearer token (`prom_live_…`). Mint one at /app/api-keys; unlocks managed code embeddings + memory.
`PROMETHEUS_WORKSPACE_ROOT`	no	auto-detected	Repository to index and query. Auto-detected via MCP `roots` / `CLAUDE_PROJECT_DIR`; set only to override.
`PROMETHEUS_DB_PATH`	no	`~/.prometheus/<hash>.db`	Override for the local SQLite index location.
`PROMETHEUS_API_URL`	no	`https://api.prom.codes`	Override for staging or self-hosted API instances.
`PROMETHEUS_REGION_MODE`	no	`default`	One of `default`, `eu-strict`, `oss-only`. See Region mode.

Environment variables — memory server

Variable	Required	Default	Purpose
`PROMETHEUS_API_KEY`	yes	—	Same `prom_live_…` key as the context server; validated at startup.
`PROMETHEUS_WORKSPACE_ROOT`	no	auto-detected	Anchors the project identity and the `.prometheus/memories/` markdown mirror. Auto-detected; set only to override.
`PROMETHEUS_MEMORY_DB_PATH`	no	`~/.prometheus/memory.db`	Override for the shared memory database location.

Environment variables — saver

Variable	Required	Default	Purpose
`PROMETHEUS_WORKSPACE_ROOT`	no	auto-detected	Repo whose runtime rule files the `setup` tool writes into. Auto-detected; set only to override.
`PROMETHEUS_API_KEY`	no	—	Not required — the saver needs no key. If set, ties the install to your account for future metering.

The saver exposes a single tool, setup (arguments: level — lite / balanced / aggressive; optional runtimes), which writes an efficient-output rule block into the workspace's runtime rule files. See Token Saver.

HTTP transport (Phase 3, in design)

For remote-only setups (browser-side agents, serverless functions, multi-tenant SaaS hosts) prom.codes will expose an HTTP/SSE transport at api.prom.codes/mcp. The wire protocol is the standard MCP streamable-HTTP binding — same tool surface, different framing.

Self-hosting the API

The prom.codes API is a Node 22 service distributed as a container image. Point PROMETHEUS_API_URL at your own deployment and you keep the entire pipeline in your VPC. A deployment template will ship alongside the public release.