# MCP Inspector Debug Guide (o11y-mcp-server)

This guide shows a practical way to debug `o11y-mcp-server` with:

- `npx @modelcontextprotocol/inspector --cli`
- real MCP config (`mcp.json`)
- startup/tool logs from the server

It also covers the most common failure we hit: **large numeric `cluster_id` precision loss**.

## 1) Prerequisites

1. Install server dependencies:

```bash
pip install -e ".[dev]"
```

2. Prepare MCP config (`mcp.json`) with server-owned auth:

```json
{
  "mcpServers": {
    "tidb-o11y": {
      "command": "o11y-mcp-server",
      "args": [],
      "env": {
        "AUTH_SERVICE_URL": "https://www.ds.us-west-2.aws.observability.tidbcloud.com",
        "GITHUB_TOKEN": "<your-real-github-token>"
      }
    }
  }
}
```

> `ghp_xxx` placeholders are not valid tokens and will fail bootstrap/auth calls.

## 2) Basic inspector checks

List tools:

```bash
npx @modelcontextprotocol/inspector --cli --config ../.vscode/mcp.json --server tidb-o11y --method tools/list
```

Call `list_metrics`:

```bash
npx @modelcontextprotocol/inspector --cli --config ../.vscode/mcp.json --server tidb-o11y --method tools/call --tool-name list_metrics --tool-arg env=prod --tool-arg deploy_type=premium --tool-arg 'cluster_id="10161575535533068800"'
```

Call `query_instant`:

```bash
npx @modelcontextprotocol/inspector --cli --config ../.vscode/mcp.json --server tidb-o11y --method tools/call --tool-name query_instant --tool-arg query=up --tool-arg env=prod --tool-arg deploy_type=premium --tool-arg 'cluster_id="10161575535533068800"'
```

## 3) Critical gotcha: `cluster_id` must be string

For large IDs, this is wrong (may lose precision):

```bash
--tool-arg cluster_id=10161575535533068800
```

This is correct (explicit JSON string):

```bash
--tool-arg 'cluster_id="10161575535533068800"'
```

If precision is lost, server logs will show a different ID and GS resolution can fail with:

- `Auth Error: Observability Global Service returned no clusters for the requested parameters.`

## 4) Turn on server debug logs

The server logs to `stderr`. Enable debug level:

```bash
export MCP_SERVER_LOG_LEVEL=DEBUG
```

Run inspector while collecting logs via a wrapper config:

```json
{
  "mcpServers": {
    "tidb-o11y-debug": {
      "command": "sh",
      "args": [
        "-c",
        "MCP_SERVER_LOG_LEVEL=DEBUG AUTH_SERVICE_URL='https://www.ds.us-west-2.aws.observability.tidbcloud.com' GITHUB_TOKEN='<token>' o11y-mcp-server 2>>/tmp/o11y-server-debug.log"
      ]
    }
  }
}
```

Then run:

```bash
npx @modelcontextprotocol/inspector --cli --config /tmp/o11y-inspector-debug.json --server tidb-o11y-debug --method tools/call --tool-name list_metrics --tool-arg env=prod --tool-arg deploy_type=premium --tool-arg 'cluster_id="10161575535533068800"'
```

Inspect logs:

```bash
cat /tmp/o11y-server-debug.log
```

Look for:

- `server_auth_bootstrap_success`
- `tool_call_start name=list_metrics ...`
- `metrics_url_resolve_request ... biz_type=...`
- `metrics_url_resolve_success ...`

## 5) Interpreting outcomes

- Inspector transport failure (`Connection closed`):
  - server process failed on startup (check stderr/log file first)
- Tool returns `Auth Error ... no clusters`:
  - first verify `cluster_id` exact string quoting
  - then verify env/deploy_type mapping and token permissions
- Tool returns success with empty data (`[]`):
  - connection/auth path is healthy; query scope likely has no matching metrics

## 6) Cross-check with direct service call

If you suspect resolver mismatch, validate GS directly using the resolved auth0 bearer token and expected params:

- `bizType` from deploy/env mapping (example: `prod-tidbcloud-nextgen`)
- `applicationID` = exact `cluster_id` string

If direct GS returns a cluster but Inspector does not, compare the server log line for `cluster_id` and `biz_type` against your curl parameters.