> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude Code, Cursor, or any MCP client to your local traces, logs, and queries

Monocle Studio includes a built-in [MCP](https://modelcontextprotocol.io/) server. This lets AI coding assistants like Claude Code, Cursor, or Codex query your local telemetry data directly — find errors, inspect traces, and debug performance issues without leaving your editor.

## Setup

The MCP server is available at `http://localhost:4200/mcp` when Monocle Studio is running.

If you also want your agents to know about Monocle Studio and how to use it, run:

```bash theme={"theme":"vesper"}
monocle studio install-agents
```

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"theme":"vesper"}
    pnpm dlx add-mcp http://localhost:4200/mcp -n monocle-studio -a claude-code
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={"theme":"vesper"}
    pnpm dlx add-mcp http://localhost:4200/mcp -n monocle-studio -a cursor
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={"theme":"vesper"}
    pnpm dlx add-mcp http://localhost:4200/mcp -n monocle-studio -a codex
    ```
  </Tab>

  <Tab title="Other">
    `add-mcp` supports 15+ clients. Run `pnpm dlx add-mcp --all` to install for all detected clients, or configure manually:

    ```json theme={"theme":"vesper"}
    {
      "mcpServers": {
        "monocle-studio": {
          "type": "url",
          "url": "http://localhost:4200/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Available tools

| Tool           | Description                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------ |
| `list_traces`  | List recent traces with entry point, duration, and status. Supports filtering by trace ID.       |
| `get_trace`    | Get the complete span waterfall for a trace — parent/child relationships, durations, attributes. |
| `list_logs`    | List logs filtered by severity, search text, or trace ID.                                        |
| `list_errors`  | List exceptions with type, message, stacktrace, and trace context.                               |
| `list_queries` | List database queries with SQL statement, duration, and system. Filter by database type.         |
| `clear_data`   | Clear all collected telemetry for a fresh debugging session.                                     |

## Examples

Once connected, you can ask your AI assistant things like:

* *"What errors happened in the last few requests?"*
* *"Show me the trace for the slow /api/users endpoint"*
* *"Find all database queries slower than 200ms"*
* *"What's the overall health of my app right now?"*
* *"Clear all data and start a fresh debugging session"*

The assistant will call the appropriate MCP tools, query Monocle Studio, and give you the answer in context.