# observe-mcp

An MCP server for querying [Observe.com](https://www.observeinc.com/) logs using OPAL. Compatible with Claude Desktop, Claude Code, and any MCP client.

## Tools

| Tool | Description |
|---|---|
| `observe_query` | Run a raw OPAL pipeline query against any dataset |
| `list_datasets` | Discover available datasets in your Observe tenant |
| `inspect_dataset` | Live-sample a dataset to see available fields |
| `get_dataset_schema` | Return cached field schema (instant, no API call) |
| `search_service_logs` | Search logs for a named service |
| `search_entity_logs` | Search logs by any field/value pair (userId, requestId, deviceId, etc.) |
| `observe_docs` | OPAL language reference and query examples |

## Configuration

| Variable | Required | Description |
|---|---|---|
| `OBSERVE_CUSTOMER_ID` | Yes | Your Observe tenant ID (numeric). Found in your Observe URL: `https://<id>.observeinc.com` |
| `OBSERVE_TOKEN` | Yes | Observe bearer token. Generate at: Observe UI → Settings → API Tokens |
| `OBSERVE_DEFAULT_DATASET` | No | Default dataset path used when `dataset_path` is not passed |

## Usage with Claude Code

```bash
claude mcp add observe docker run -i --rm \
  -e OBSERVE_CUSTOMER_ID=<your-id> \
  -e OBSERVE_TOKEN=<your-token> \
  staffdill/observe-mcp
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "observe": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OBSERVE_CUSTOMER_ID=<your-id>",
        "-e", "OBSERVE_TOKEN=<your-token>",
        "staffdill/observe-mcp"
      ]
    }
  }
}
```

## Schema Cache

`get_dataset_schema` returns instant results from a local cache file (`data/fields.json`). This file is tenant-specific and not included in the image. If the cache is absent, use `inspect_dataset` for a live field sample instead.

## License

MIT