@mantisai/mcp

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

Installation

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

Authentication

Two authentication modes are supported:

| Mode | Scope | Env Vars | |------|-------|----------| | Personal Access Token (PAT) | Multi-project | MANTIS_API_TOKEN | | API Key Pair (BasicAuth) | Single project | MANTIS_SECRET_KEY + MANTIS_PUBLIC_KEY |

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

Programmatic Client

import { MantisClient } from '@mantisai/mcp';

// PAT mode (multi-project)
const client = new MantisClient({
  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 insights = await client.searchInsights({
  projectId: 'proj-abc',
  query: 'error handling failures',
});

MCP Server (for AI Agents)

Run as a stdio MCP server. MANTIS_URL defaults to https://insight.withmetis.ai if not set.

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

# BasicAuth mode (single project) — uses default URL
MANTIS_SECRET_KEY=sk-lf-... MANTIS_PUBLIC_KEY=pk-lf-... npx @mantisai/mcp serve

# Custom instance
MANTIS_URL=http://localhost:3000 MANTIS_API_TOKEN=pat_... npx @mantisai/mcp serve

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mantis": {
      "command": "npx",
      "args": ["@mantisai/mcp", "serve"],
      "env": {
        "MANTIS_API_TOKEN": "pat_a1b2c3d4..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "mantis": {
      "command": "npx",
      "args": ["@mantisai/mcp", "serve"],
      "env": {
        "MANTIS_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)

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_insights — Semantic vector search over score reasoning and comments

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MANTIS_URL | No | Mantis instance URL. Defaults to https://insight.withmetis.ai | | MANTIS_API_TOKEN | PAT mode | Personal access token (pat_xxx) | | MANTIS_SECRET_KEY | BasicAuth mode | Secret key (sk-lf-xxx) | | MANTIS_PUBLIC_KEY | BasicAuth mode | Public key (pk-lf-xxx) |