Query logs with Claude Code

This guide connects 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.
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. 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):

{
  "mcpServers": {
    "apoxy": {
      "type": "http",
      "url": "https://api.apoxy.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with the key you created above.

2. Add the plugin marketplace in Claude Code:

/plugin marketplace add apoxy-dev/claude-plugin

3. Install the plugin from the marketplace:

/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 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.