# Query logs with Claude Code

> Connect Claude Code to Apoxy's MCP server to query your proxy logs with natural language.

This guide connects [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to your Apoxy project so you can query Envoy proxy access logs by asking questions in natural language.

## Prerequisites

- Claude Code installed (`npm install -g @anthropic-ai/claude-code`).
- An Apoxy project with proxies generating traffic.
- An API key from the Apoxy console.

## Create an API key

1. Open the [Apoxy console](https://dashboard.apoxy.dev).
2. Click your avatar in the top right.
3. Go to **Account Settings > API Keys**.
4. Create a new key and copy it.

## Install the plugin

The easiest way to get started is with the [Apoxy Claude plugin](https://github.com/apoxy-dev/claude-plugin). It configures the MCP server and adds a skill that teaches Claude how to query your logs effectively.

1. Add the MCP server to your project's `.mcp.json` (create it if it doesn't exist):

```json title=".mcp.json"
{
  "mcpServers": {
    "apoxy": {
      "type": "http",
      "url": "https://api.apoxy.dev/mcp",
      "headers": {
        "X-Apoxy-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` with the key you created above.

2. Add the plugin marketplace in Claude Code:

```bash title="terminal"
/plugin marketplace add apoxy-dev/claude-plugin
```

3. Install the plugin from the marketplace:

```bash title="terminal"
/plugin install apoxy-query@apoxy
```

The plugin provides a skill that teaches Claude PRQL query patterns, field names, types, and best practices for querying your proxy logs.

## Verify the connection

Start Claude Code and check that the `apoxy` MCP server is connected. You should see two tools available:

- **`describe_schema`** — Lists all available log fields and their types.
- **`query`** — Executes PRQL queries against your proxy logs.

Try asking:

> What fields are available in my proxy logs?

Claude will call `describe_schema` and show you the available fields.

## Example queries

Ask Claude questions about your traffic in natural language:

> Show me the last 10 requests that returned 5xx errors.

> What are the top URL paths by request count in the last hour?

> Are there any requests with latency over 500ms?

> Break down traffic by HTTP method for the last 24 hours.

> Show me all requests to /api/users that returned 404.

Claude translates your questions into [PRQL](https://prql-lang.org/) queries and runs them against your Envoy access logs. Each response includes the compiled SQL so you can see exactly what was executed.

## Tips

- **Start broad, then narrow.** Ask for a summary first, then drill into specific status codes, paths, or time ranges.
- **Use time ranges.** Claude defaults to the last 24 hours. Ask for a specific window if you need it: "Show me errors between 2pm and 3pm today."
- **Combine filters.** You can ask for compound conditions: "Show me POST requests to /api that returned 500 with latency over 100ms."
- **Paginate large results.** Results are paginated automatically. Ask Claude to "show more" to fetch the next page.

## Available fields

For a full list of queryable fields and their types, see the [MCP Server reference](/docs/docs/reference/mcp.md#log-fields).