Skip to main content

Codex Integration

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

Prerequisites​

  • Codex CLI installed on your machine
  • An active Oodle instance

The Oodle CLI provides a one-command setup that handles OAuth authentication automatically, including token refresh — no manual token management required.

Step 1: Install the Oodle CLI​

If you don't have the Oodle CLI installed, install it via Homebrew:

brew tap oodle-ai/oodle
brew install oodle

Step 2: Set up Codex​

oodle mcp setup codex --deployment DEPLOYMENT

Replace DEPLOYMENT with your deployment identifier (e.g., us1, ap1).

This opens a browser window for authentication (if needed) and patches ~/.codex/config.toml to run an Oodle MCP proxy via stdio. The proxy injects a fresh OAuth token on every request and refreshes it automatically when it expires.

Step 3: Restart Codex​

Restart Codex for the changes to take effect. That's it — no API keys or tokens to copy.

tip

You can re-run oodle mcp setup codex at any time to update the configuration. Use the --name flag to customise the MCP server name (defaults to oodle-ai).

Configuration with API Key​

If you prefer not to use the Oodle CLI, you can configure Codex with an API key directly.

Step 1: Get Your API Key​

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

Step 2: Configure Codex​

Add the following to ~/.codex/config.toml:

[mcp_servers.oodle-ai]
url = "https://YOUR_DEPLOYMENT.oodle.ai/v1/api/instance/YOUR_INSTANCE/mcp"
http_headers = { "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 configuration from the Codex (MCP) integration card in your Oodle instance settings. It includes your instance ID and API key pre-filled.

Step 3: Restart Codex​

After saving config.toml, restart Codex for the changes to take effect.

Usage​

Once configured, you can query your observability data directly in Codex'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​

By default, all tools are available. To limit the MCP server to specific tool categories, the method depends on how you configured Codex.

With OAuth (Oodle CLI)​

Pass the --toolsets flag when running setup:

oodle mcp setup codex --deployment DEPLOYMENT --toolsets logs,metrics

With API Key​

Append the toolsets query parameter to the MCP URL in ~/.codex/config.toml:

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
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 Codex​

  1. Verify the MCP server was added successfully by running: 
    codex mcp list
  2. If using Oodle CLI setup, verify your auth is still valid: 
    oodle auth token
    If expired, re-run oodle mcp setup codex --deployment DEPLOYMENT.
  3. If using API key setup, check that the key is valid and has not expired
  4. Ensure Codex was fully restarted after adding the MCP server
  5. Check Codex'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​

  • With the Oodle CLI setup, OAuth tokens are managed automatically and never stored in Codex's configuration — the oodle mcp serve proxy injects them at runtime
  • With API key setup, keys are stored locally in ~/.codex/config.toml
  • 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: