OpenSearch MCP Agent

A custom Model Context Protocol (MCP) server that lets Claude Code query OpenSearch clusters protected by OpenID Connect (Azure AD) authentication — without direct CLI access to the cluster.

Read the journey of building this solution in From Hours to Seconds: Building an AI-Powered OpenSearch Log Analyzer with Claude

Problem

• OpenSearch clusters sit behind OpenSearch Dashboards with OIDC / Azure AD auth
• No direct CLI or API key access to the cluster
• The official opensearch-mcp-server-py doesn't support cookie/session-based OIDC auth

How It Works

The MCP server makes direct HTTP calls to the same internal API endpoint (/internal/search/opensearch-with-long-numerals) that the Dashboards UI uses, authenticated with browser session cookies.

Claude Code → MCP (stdio) → server.py → HTTP POST → OpenSearch Dashboards APIs → OpenSearch

There is no proxy or standalone OpenSearch server involved.

Features

• Cookie-based OIDC auth — uses the same session cookies as the browser
• Auto cookie refresh — on 401, launches headless Playwright to re-authenticate via cached SSO session
• Context optimization — auto-prune, field filtering, summary-only mode, per-hit truncation, and 15KB response cap to keep Claude's context window lean
• Response metadata — every response includes _meta.applied_operations so Claude knows what was filtered/truncated
• Multi-cluster support — Support any number of clusters
• Claude skill — built-in skill teaching Claude cost-conscious query patterns

Available Tools

Prerequisites

• Python 3.10+
• Claude Code CLI
• Access to an OpenSearch Dashboards instance with OIDC/Azure AD auth

Quick Setup

1. Run the initialization script

./init.sh

This script will:

• ✓ Check Python version (requires 3.10+)
• ✓ Create a virtual environment at venv/
• ✓ Install all dependencies (mcp, httpx, playwright)
• ✓ Install Chromium browser (for cookie auto-refresh)
• ✓ Create .env from .env.example (for cluster URLs)
• ✓ Generate .mcp.json with correct absolute paths
• ✓ Verify the setup

2. Add your cluster URLs

Edit .env (auto-created from .env.example by init.sh) and fill in your actual OpenSearch cluster URLs:

3. Fetch authentication cookies

source venv/bin/activate

# List available clusters (from clusters.py)
./get-cookies.py --list

# Fetch cookies for your cluster (opens browser for SSO login)
./get-cookies.py <cluster-short-name>

# Deactivate venv
deactivate

This writes cookies.json which the server reads on every request. This is one-time setup — the MCP server will auto-refresh cookies after this.

4. Start Claude Code

claude

Claude will automatically load the MCP server and have access to all OpenSearch tools.

Manual Setup (if needed)

1. Create virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Install Playwright (for cookie auto-refresh)

pip install playwright
playwright install chromium

3. Update .mcp.json with correct paths

{
  "mcpServers": {
    "opensearch": {
      "type": "stdio",
      "command": "/absolute/path/to/project/venv/bin/python",
      "args": ["/absolute/path/to/project/server.py"],
      "env": {
        "OPENSEARCH_URL": "https://opensearch-dashboard.example.com",
        "OPENSEARCH_VERIFY_SSL": "true"
      }
    }
  }
}

4. Configure your clusters

Copy .env.example to .env and fill in your actual cluster URLs.

5. Fetch cookies

Follow step 3 from Quick Setup above.

Usage Examples

Once set up, you can ask Claude things like:

• "Search for errors in the my-namespace namespace in the last hour"
• "How many logs were generated by pod api-server-xyz today?"
• "Show me logs containing request ID 77e71a17-2e52-404a-86d2-eed997fd2a57"
• "What are the top 10 namespaces by log volume in the last 24 hours?"
• "Check cluster health"

Claude uses a cost-conscious query strategy: count first (summary_only), sample with field filtering, aggregate for analysis, and full fetch only when needed.

Cookie Management

Automatic refresh

When cookies expire (401), the server automatically:

1. Launches a headless Playwright browser
2. Uses the cached Azure AD SSO session to get fresh cookies
3. Saves to cookies.json and retries the request transparently

Manual refresh

If the SSO session itself has expired:

./get-cookies.py <cluster-short-name>

This opens a browser for interactive login. After login, cookies are saved — no Claude Code restart needed.

Switching clusters

source venv/bin/activate
./get-cookies.py <cluster-short-name>
deactivate

Project Structure

opensearch-agent/
├── init.sh                            # Setup automation script (run this first!)
├── .env.example                       # Cluster URL template (tracked)
├── .env                               # Your cluster URLs (gitignored, created by init.sh)
├── .mcp.json                          # MCP server config (auto-generated, gitignored)
├── .gitignore                         # Ignores venv/, cookies, logs, .env, etc.
├── README.md                          # This file
├── CLAUDE.md                          # Detailed knowledge base & learnings
├── server.py                          # MCP server (cookie auth, auto-refresh, context optimization)
├── clusters.py                        # Cluster registry (loads URLs from .env, descriptions in source)
├── get-cookies.py                     # Playwright-based cookie fetcher (multi-cluster SSO)
├── requirements.txt                   # Python dependencies
├── cookies.json                       # Auto-managed cookie store (gitignored)
├── server.log                         # Debug logs (gitignored)
├── venv/                              # Python virtual environment (gitignored)
├── .browser-data/                     # Playwright persistent browser profile (gitignored)
└── .claude/
    └── skills/
        └── opensearch/
            └── SKILL.md               # Claude skill for query patterns

Context Optimization

The server optimizes responses to minimize Claude's context window usage:

Dependencies

• mcp >= 1.0.0 — Model Context Protocol SDK
• httpx >= 0.27.0 — HTTP client
• playwright — Browser automation for cookie refresh