@charleswrightgateway/mcp

TypeScript SDK for the Gateway trace analysis platform. Use it as a programmatic client in your code or as an MCP server for AI agents.

Installation

npm install @charleswrightgateway/mcp
# or
pnpm add @charleswrightgateway/mcp

Authentication

Two authentication modes are supported:

| Mode | Scope | Env Vars | |------|-------|----------| | Personal Access Token (PAT) | Multi-project | GATEWAY_API_TOKEN | | API Key Pair (BasicAuth) | Single project | GATEWAY_SECRET_KEY + GATEWAY_PUBLIC_KEY |

Create a PAT in Account Settings → Access Tokens, or find project-scoped keys in Project Settings → API Keys.

Programmatic Client

import { GatewayClient } from '@charleswrightgateway/mcp';

// PAT mode (multi-project)
const client = new GatewayClient({
  url: 'https://your-instance.example.com',
  token: 'pat_a1b2c3d4...',
});

// Discover projects
const { projects } = await client.listProjects();

// Get context (schema, workflow, query reference)
const context = client.getContext();

// Explore a project
const stats = await client.describeProject({ projectId: 'proj-abc' });

// Fetch traces (with pagination)
const trace = await client.getTrace({
  projectId: 'proj-abc',
  traceIds: ['trace-1', 'trace-2'],
  observationOffset: 0,
  observationLimit: 50,
});

// Run a single SQL query
const result = await client.executeQuery({
  projectId: 'proj-abc',
  sql: 'SELECT name, COUNT(*) as cnt FROM traces GROUP BY name LIMIT 10',
});

// Run batch queries in parallel
const batch = await client.executeQuery({
  projectId: 'proj-abc',
  queries: [
    { id: 'costs', sql: 'SELECT trace_id, SUM(total_cost) as cost FROM observations GROUP BY trace_id ORDER BY cost DESC LIMIT 5' },
    { id: 'counts', sql: 'SELECT name, COUNT(*) as cnt FROM traces GROUP BY name LIMIT 10' },
  ],
});

// Semantic search
const gateways = await client.searchGateways({
  projectId: 'proj-abc',
  query: 'error handling failures',
});

MCP Server (for AI Agents)

Run as a stdio MCP server. GATEWAY_URL defaults to https://app.gateway.dev if not set.

# PAT mode (multi-project) — uses default URL
GATEWAY_API_TOKEN=pat_... npx @charleswrightgateway/mcp serve

# BasicAuth mode (single project) — uses default URL
GATEWAY_SECRET_KEY=sk-lf-... GATEWAY_PUBLIC_KEY=pk-lf-... npx @charleswrightgateway/mcp serve

# Custom instance
GATEWAY_URL=http://localhost:3000 GATEWAY_API_TOKEN=pat_... npx @charleswrightgateway/mcp serve

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["@charleswrightgateway/mcp", "serve"],
      "env": {
        "GATEWAY_API_TOKEN": "pat_a1b2c3d4..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["@charleswrightgateway/mcp", "serve"],
      "env": {
        "GATEWAY_API_TOKEN": "pat_a1b2c3d4..."
      }
    }
  }
}

Available Tools

Local (no network):

• get_context — Database schema, available tools, query patterns, and recommended workflow
• list_projects — All projects accessible to the authenticated user (PAT mode only)

Discovery:

• guide — Detailed help by topic (overview, tools, schema, queries, tips, auto_improvement)

Proxied (requires project_id in PAT mode):

• describe_project — Row counts, score configs, score aggregates, observation types, session counts, tags, time range
• get_trace — Fetch up to 10 traces with observations and scores (paginated)
• get_session — Fetch up to 5 sessions with trace summaries (paginated)
• get_observations — Fetch up to 20 observations by ID with full input/output content
• diff_traces — Side-by-side comparison of two traces
• trace_stats — Cost and latency rollup grouped by trace name with p50/p95 latency
• execute_query — Read-only ClickHouse SQL; pass sql for single or queries array for up to 10 in parallel
• search_gateways — Semantic vector search over score reasoning and comments

Context Hub (the prompts/skills/agents under analysis):

• search_context — Find context-hub items by kind (prompt/skill/memory/agent) + query → ids + handles
• get_context_item — Read a context-hub item's files at a version

Dreams (analysis agents that propose improvements):

• list_dreams — List dream configs with targets + latest run status
• get_dream — Full config detail; pass runId to expand a run's proposals/suggestions
• configure_dream — Create/update a dream targeting context items + evaluators
• run_dream — Enqueue a dream run (gated by MCP_DREAM_TRIGGER_ENABLED, default on); returns runId
• review_dream_outputs — List a dream run's proposals/suggestions; accept/reject one by itemId (accept/reject gated by MCP_DREAM_AUTOAPPLY_ENABLED, default off)

A dream is an analysis agent that inspects the project's traces plus the context-hub items and evaluators it targets, then proposes improvements (prompt edits, new/updated evaluators). These tools chain into an auto-improvement loop: describe_project/execute_query (find failing patterns) → search_context (find the prompt/agent at fault) → configure_dream → run_dream → poll get_dream(runId) → review_dream_outputs (accept the safe changes) → re-measure. Call guide("auto_improvement") for the full playbook.

Some tools (prompt-management, dream run/review) are surfaced only when the server enables them. The proxy auto-discovers whatever the server exposes, so call tools/list for the live set.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GATEWAY_URL | No | Gateway instance URL. Defaults to https://app.gateway.dev | | GATEWAY_API_TOKEN | PAT mode | Personal access token (pat_xxx) | | GATEWAY_SECRET_KEY | BasicAuth mode | Secret key (sk-lf-xxx) | | GATEWAY_PUBLIC_KEY | BasicAuth mode | Public key (pk-lf-xxx) |