npm package: @mantisai/mcp
Description: MCP server and client for Mantis trace analysis platform
Latest version: 0.1.0

# @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

```bash
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

```typescript
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.

```bash
# 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`:

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

### Cursor

Add to `.cursor/mcp.json`:

```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`) |