Model Context Protocol (MCP)

The Model Context Protocol is an open standard introduced by Anthropic that defines how AI applications connect to external tools and data sources. It's analogous to LSP for editors: one protocol, many clients, many servers.

!!! info "Availability" The MCP server is available in Open Source, Enterprise Edition, and Cloud. OAuth 2.0 sign-in for MCP is available in Enterprise Edition with Dex enabled.

You can connect your AI agents and IDEs to your OpenObserve instance to query logs, metrics, and traces in natural language; create and manage alerts; and explore stream metadata directly from your editor or agent runtime. MCP enables:

• Natural-language queries against logs, metrics, and traces from your IDE
• Agentic operations like alert creation as part of CI/CD pipelines
• AI-assisted troubleshooting where an agent can pull stream data, correlate traces, and suggest root causes

Prerequisites

Your MCP endpoint follows the pattern:

https://your-instance/api/{org_id}/mcp

Authentication

The MCP server supports two authentication methods:

• Basic authentication works in all editions. Generate a Base64-encoded token from your OpenObserve credentials:

  echo -n "your-email@example.com:your-password" | base64

  You'll use this token in every client below.

• OAuth 2.0 sign-in is available in Enterprise Edition with Dex enabled. The client signs in through the browser, so you do not create or store a token.

OAuth 2.0 sign-in

With OAuth, add the MCP endpoint to your client without an Authorization header. For example, with Claude Code:

claude mcp add o2 https://your-instance/api/default/mcp -t http

The client completes the sign-in on its own:

1. The client calls https://your-instance/api/{org_id}/mcp and receives a 401 response with a WWW-Authenticate header that points to the server's OAuth protected resource metadata (RFC 9728).
2. From that metadata the client discovers the Dex authorization server, registers itself through dynamic client registration, and opens a browser window for sign-in.
3. After you sign in, the client sends a bearer token in the Authorization header on every request.

Server requirements for OAuth sign-in:

• Dex is enabled, and the Dex URL is reachable from the machine that runs the MCP client.
• ZO_WEB_URL and ZO_BASE_URI are set to the externally visible address of your instance. The server uses them to build the metadata URLs that the client follows.
• The Dex configuration permits dynamic client registration and the scopes openid, email, groups, profile, and offline_access.

Connect to OpenObserve's MCP server

{
  "mcpServers": {
    "openobserve": {
      "url": "https://your-instance/api/default/mcp",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_TOKEN>"
      }
    }
  }
}

{
  "servers": {
    "openobserve": {
      "type": "http",
      "url": "https://your-instance/api/default/mcp",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_TOKEN>"
      }
    }
  }
}

claude mcp add openobserve https://your-instance/api/default/mcp \
  -t http \
  --header "Authorization: Basic <YOUR_BASE64_TOKEN>"

claude mcp list

{
  "mcpServers": {
    "openobserve": {
      "url": "https://your-instance/api/default/mcp",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_TOKEN>"
      }
    }
  }
}

{
  "mcpServers": {
    "openobserve": {
      "url": "https://your-instance/api/default/mcp",
      "headers": {
        "Authorization": "Basic <YOUR_BASE64_TOKEN>"
      }
    }
  }
}

Building autonomous agents

For agentic workflows outside an IDE, call the MCP server directly over HTTP. We recommend creating a dedicated user with scoped permissions for agent use.

# start_time / end_time are epoch microseconds; this example queries the last hour
START=$(python3 -c "import time; print(int((time.time() - 3600) * 1_000_000))")
END=$(python3 -c "import time; print(int(time.time() * 1_000_000))")

curl https://your-instance/api/default/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <YOUR_BASE64_TOKEN>" \
  -d @- <<EOF
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "SearchSQL",
    "arguments": {
      "org_id": "default",
      "request_body": {
        "query": {
          "sql": "SELECT * FROM logs WHERE level = 'error' LIMIT 10",
          "start_time": $START,
          "end_time": $END,
          "from": 0,
          "size": 10
        }
      }
    }
  },
  "id": 1
}
EOF

The SearchSQL request body supports agent_options for agent-friendly responses. Set output_format to csv or md_table to reduce the token count of results, and set mode to partition to scan long time ranges in a single request without SSE streaming. See Agent options in the search API reference for details.

When you set output_format, also set the tool call's detail argument to full. The default summary detail level keeps only the standard response fields and strips the data block that carries the formatted results.

This pattern works with OpenAI's Responses API, Anthropic's API, and any agent runtime that supports remote MCP servers.

Available tools

OpenObserve includes the following tools. Tool names are prefixed with your server name (e.g. mcp__openobserve__StreamList).

Legend: pinned = exposed directly in the initial tools/list response (no search required) · ⚠️ = destructive (modifies or deletes data)

Multi-organization workflows

Each organization in your OpenObserve instance has its own MCP endpoint. You can register multiple servers in a single client to switch contexts. The example below uses the Claude Code CLI, but the same pattern applies to every client covered above: add one entry per org in the relevant config file (mcp.json, claude_desktop_config.json, etc.).

claude mcp add o2-prod https://your-instance/api/production/mcp \
  -t http --header "Authorization: Basic <PROD_TOKEN>"

claude mcp add o2-dev https://your-instance/api/development/mcp \
  -t http --header "Authorization: Basic <DEV_TOKEN>"

This is useful for keeping production data isolated from development queries, or for SaaS deployments where each tenant has its own org.

Security considerations

!!! warning "Permission scoping in Open Source" Role-based access control with custom roles and granular permissions is available in Enterprise Edition and Cloud. On an Open Source instance, every MCP tool call runs with the connected account's full privileges. This includes the destructive tools marked ⚠️ in the tool tables above, such as deleting streams, alerts, and users. Before connecting an AI agent to an Open Source instance, restrict network access to the endpoint and configure your MCP client to require confirmation for every tool call.

• Use a dedicated MCP user with the minimum permissions required, rather than your personal admin credentials. Permission scoping requires role-based access control, which is available in Enterprise Edition and Cloud.
• Never commit credentials to version control. Store Base64 tokens in environment variables or a secrets manager.
• Rotate credentials regularly and revoke access for any client you no longer use.
• Confirm tool calls before execution in your MCP client when possible. This protects against prompt injection from untrusted data sources.
• Use organization-specific endpoints to limit blast radius. A token for org_a cannot access org_b.
• Restrict network access to the MCP endpoint via firewall rules or IP allowlisting where feasible.

Troubleshooting

# Verify your Base64 token decodes correctly
echo "<YOUR_BASE64_TOKEN>" | base64 -d
# Should print: your-email@example.com:your-password

# Test credentials against the meta endpoint
curl -u "username:password" https://your-instance/api/default/_meta

Next steps

• Claude Code MCP setup: step-by-step walkthrough for the Claude Code CLI.
• Building autonomous agents: call the MCP server directly from your own agent runtime.
• MCP Protocol Specification: the open standard behind every client and server.
• GitHub Issues: file bugs or feature requests.

Need some help?

• Join our Community Slack
• Or Contact support