# 021-mcp

MCP server for interacting with LLM traces. Search, analyze, and debug your AI agent executions through any MCP-compatible client.

## Installation

```bash
pip install 021-mcp
```

Or with [uvx](https://docs.astral.sh/uv/):

```bash
uvx 021-mcp
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TRACES_API_KEY` | Yes | Your API key for authentication |
| `TRACES_BASE_URL` | No | Base URL of the traces API (default: `https://api.021labs.ai`) |

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "traces": {
      "command": "uvx",
      "args": ["021-mcp"],
      "env": {
        "TRACES_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Manus

Add to your Manus MCP configuration:

```json
{
  "servers": {
    "traces": {
      "command": "uvx",
      "args": ["021-mcp"],
      "env": {
        "TRACES_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor / Other MCP Clients

Most MCP clients support a similar configuration format. The key elements are:

- **command**: `uvx` (or `python -m mcp_traces.server` if installed via pip)
- **args**: `["021-mcp"]`
- **env**: Must include `TRACES_API_KEY`

## Available Tools

### `list_traces`

List traces with optional filters.

**Parameters:**
- `status` - Filter by status: SUCCESS, ERROR, or RUNNING
- `search` - Full-text search query
- `start_time` - Filter traces after this ISO timestamp
- `end_time` - Filter traces before this ISO timestamp
- `session_id` - Filter by session ID
- `user_id` - Filter by user ID
- `project_id` - Filter by project ID
- `limit` - Maximum results (1-100, default 20)

**Example usage:**
> "Show me the last 10 traces that failed"
> "Find traces from yesterday that mention 'database'"

### `get_trace`

Get detailed information about a specific trace.

**Parameters:**
- `trace_id` - The trace ID to fetch
- `include_io` - Include full input/output data (default: false)

**Example usage:**
> "Get details for trace abc123"
> "Show me trace xyz789 with all the LLM inputs and outputs"

### `get_span`

Get full details for a specific span including input/output.

**Parameters:**
- `span_id` - The span ID to fetch

**Example usage:**
> "What was the input to span def456?"
> "Show me the LLM response in span ghi789"

### `get_analytics`

Get analytics summary for traces.

**Parameters:**
- `start_time` - Start of time range
- `end_time` - End of time range
- `granularity` - hour, day, or week (default: day)
- `project_id` - Filter by project ID

**Example usage:**
> "Show me trace analytics for the last week"
> "What's the error rate for project X?"

### `search_errors`

Find recent traces that ended in errors.

**Parameters:**
- `limit` - Maximum results (default: 10)
- `start_time` - Filter errors after this timestamp
- `project_id` - Filter by project ID

**Example usage:**
> "Find recent errors"
> "What failed in the last hour?"

## Development

```bash
# Clone and install
git clone https://github.com/021labs/rl.git
cd rl/packages/mcp

# Install dependencies
uv sync

# Run locally
uv run 021-mcp

# Run tests
uv run pytest
```

## License

MIT
