Skip to main content

Claude Code Integration

Claude Code is Anthropic's AI-powered coding assistant. By integrating Oodle with Claude Code, you can query your observability data directly from the AI assistant while coding.

Prerequisites​

  • Claude Code installed on your machine
  • An active Oodle instance
  • Oodle API key (Admin, Editor, or Viewer)

Configuration​

Step 1: Get Your API Key​

  1. Log in to your Oodle instance
  2. Navigate to Settings → Integrations
  3. Find the Claude Code (MCP) integration card
  4. Copy the command from the configuration

Step 2: Configure Claude Code​

  1. Run the following command in your terminal to add Oodle as an MCP server:
claude mcp add --transport http oodle-ai \
  https://YOUR_DEPLOYMENT.oodle.ai/v1/api/instance/YOUR_INSTANCE/mcp \
  --header "X-API-KEY: YOUR_API_KEY"

Replace:

  • YOUR_DEPLOYMENT with your Oodle deployment domain
  • YOUR_INSTANCE with your Oodle instance ID
  • YOUR_API_KEY with your Oodle API key
tip

You can copy the exact command from the Claude Code (MCP) integration card in your Oodle instance settings. It includes your instance ID and API key pre-filled.

Step 3: Restart Claude Code​

After adding the MCP server, restart Claude Code for the changes to take effect.

OAuth Configuration (Alternative)​

Instead of using an API key, you can authenticate via OAuth. This uses the standard MCP OAuth flow built into Claude Code:

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID --callback-port 9400 \
  oodle-ai https://YOUR_DEPLOYMENT.oodle.ai/v1/api/instance/YOUR_INSTANCE/mcp

After adding the server, run /mcp in Claude Code and follow the browser login flow to complete authentication. The OAuth token is stored securely in your system keychain.

Configuration using Integration tile​

Claude Code Integration

You can find the required Claude Code configuration by doing the following:

  1. Login to the Oodle UI, then navigate to Settings page
  2. Click on the Claude Code tile
  3. Choose an appropriate API key from the list on top of the drawer

Follow the steps specified in the drawer to integrate Oodle into your Claude Code

Usage​

Once configured, you can query your observability data directly in Claude Code's AI assistant. Here are some example queries:

Query Logs​

Show me error logs from the last hour
What are the most common error messages in the auth-service?
Find all logs containing "timeout" from yesterday

Query Metrics​

What's the current CPU usage across all services?
Show me the request rate for the API service over the last 24 hours
Is there any metric that shows memory spikes?

Query Traces​

Show me slow traces from the checkout service
Find traces that took longer than 5 seconds
Get the trace with ID abc123xyz

Check Alerts​

Are there any active alerts right now?
Show me alerts that fired in the last 6 hours
What monitors are configured for the database service?

Query Dashboards​

Show me the dashboard for the API service
What's the current value of the "Request Rate" panel?
Find all dashboards related to Kubernetes

Available Tools​

The Oodle MCP server provides comprehensive observability tools across the following categories:

Logs​

Query and filter logs with flexible time ranges and field-based filtering. Discover available fields and run aggregations to analyze log patterns.

Metrics​

Execute PromQL queries to access your metrics data. Search for metrics, explore labels, and validate queries.

Traces​

Search distributed traces by service, operation, or custom tags. Retrieve specific trace details and explore available trace attributes.

Alerts​

Access active alerts, view monitor configurations, and check historical trigger data to understand your alerting landscape.

Grafana​

Interact with Grafana dashboards programmatically. Search, retrieve, update dashboards, and query panel data directly. Dashboard write operations (save/update) require an Editor or Admin API key.

RUM (Real User Monitoring)​

Query user sessions, browse session events, and investigate frontend issues and errors reported by the RUM SDK.

Integrations​

Discover available integrations and retrieve setup specifications for onboarding new data sources.

Filtering Tools​

Filtering Tools by Category​

By default, all tools are available when you connect to the Oodle MCP server. To limit the server to specific tool categories, append the toolsets query parameter to the MCP URL:

https://YOUR_DEPLOYMENT.oodle.ai/v1/api/instance/YOUR_INSTANCE/mcp?toolsets=logs,metrics

Available toolsets:

ToolsetDescription
logsLog querying, filtering, field discovery, and aggregations
metricsPromQL queries, metric/label discovery, query validation
tracesTrace search, retrieval, and label exploration
alertsActive alerts, monitors, trigger history, anomalies
grafanaDashboard search, retrieval, and management
rumReal User Monitoring sessions, issues, and errors
integrationsIntegration discovery and setup specifications

Specify multiple toolsets as a comma-separated list. For example, to expose only logs and metrics tools:

?toolsets=logs,metrics
tip

Limiting toolsets reduces the number of tools exposed to the AI assistant, which can improve response quality by reducing context noise when you only need a subset of capabilities.

Troubleshooting​

Tools not showing up in Claude Code​

  1. Verify the MCP server was added successfully by running: 
    claude mcp list
  2. Check that the API key is valid and has not expired
  3. Ensure Claude Code was fully restarted after adding the MCP server
  4. Check Claude Code's logs for any MCP-related errors

Authentication errors​

  1. Verify your API key is correct
  2. Check that your instance ID matches your Oodle instance
  3. Ensure your API key has not expired
  4. Try regenerating your API key from the Oodle UI

Tool execution errors​

  1. Verify your Oodle instance is accessible
  2. Check that your API key role has access to the requested tool — Viewer keys cannot call write tools (e.g., save/update Grafana dashboards)
  3. Ensure your query parameters are valid (e.g., valid time ranges)

Connection refused​

  1. Check your internet connection
  2. Verify the Oodle API endpoint URL is correct
  3. Ensure no firewall or proxy is blocking the connection

Best Practices​

  1. Be specific: Provide clear context in your queries (time ranges, service names, etc.)
  2. Start broad: Begin with general queries and narrow down as needed
  3. Use natural language: The AI assistant understands context, no need for exact syntax
  4. Combine tools: Ask questions that might require multiple tools (e.g., "Show me logs and metrics for errors")
  5. Iterate: If results aren't what you expected, refine your query with more context

Security​

  • API keys are stored locally in Claude Code's configuration
  • All communication is over HTTPS
  • API keys can be rotated from the Oodle UI at any time
  • Each API key is scoped to a specific Oodle instance

Support

If you need assistance or have any questions, please reach out to us through: