Setup

Configure your MCP client to connect to OwlMetry — Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Zed, JetBrains, Cline, and Roo Code.

Prerequisites

You need an agent API key (owl_agent_*) to connect. Create one from your dashboard:

Open the API Keys page in the dashboard
Click New Key
Select 🕶️ Agent as the key type
Give it a name (e.g., "Cursor MCP" or "Claude Code")
Click Create — copy the key immediately, it is only shown once

Agent keys get all permissions by default and are scoped to your team. You can customize permissions at creation time. See Authentication for details on key types and permissions.

Endpoint URL

Environment	URL
Hosted (owlmetry.com)	`https://api.owlmetry.com/mcp`
Self-hosted	`https://your-server.com/mcp`
Local development	`http://localhost:4000/mcp`

Editor Setup

claude mcp add --transport http owlmetry https://api.owlmetry.com/mcp \
  --header "Authorization: Bearer owl_agent_YOUR_KEY_HERE"

Add --scope user to make it available across all projects, or --scope project to share it via .mcp.json in a repo.

Verify the connection:

/mcp

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "owlmetry": {
      "type": "http",
      "url": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "owlmetry": {
      "type": "streamable-http",
      "url": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

You can also add servers via the Command Palette: MCP: Add Server.

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "owlmetry": {
      "type": "http",
      "url": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "owlmetry": {
      "type": "http",
      "serverUrl": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

Windsurf uses serverUrl instead of url — this is different from other editors.

You can also access this file via Windsurf settings: Cascade > MCP Servers > View raw config.

Add to your Zed settings file (~/.config/zed/settings.json):

{
  "context_servers": {
    "owlmetry": {
      "settings": {
        "url": "https://api.owlmetry.com/mcp",
        "headers": {
          "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
        }
      }
    }
  }
}

Zed uses context_servers as the root key instead of mcpServers, and nests config under settings.

In any JetBrains IDE (IntelliJ, WebStorm, PyCharm, etc.):

Open Settings > Tools > AI Assistant > Model Context Protocol (MCP)
Click + to add a new server
Enter the configuration:

{
  "mcpServers": {
    "owlmetry": {
      "type": "sse",
      "url": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

JetBrains currently uses SSE transport. Streamable HTTP support may vary by IDE version — check the JetBrains MCP docs for the latest.

Open the Cline sidebar in VS Code, click the MCP Servers icon, then Edit MCP Settings:

{
  "mcpServers": {
    "owlmetry": {
      "type": "http",
      "url": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

Add to .roo/mcp.json in your project root (or edit global settings via the Roo Code server icon):

{
  "mcpServers": {
    "owlmetry": {
      "type": "streamable-http",
      "url": "https://api.owlmetry.com/mcp",
      "headers": {
        "Authorization": "Bearer owl_agent_YOUR_KEY_HERE"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect to OwlMetry. The endpoint uses:

Transport: Streamable HTTP (POST only)
URL: https://api.owlmetry.com/mcp
Auth: Authorization: Bearer owl_agent_YOUR_KEY_HERE header
Mode: Stateless JSON — each request is independent, no session initialization needed

Authentication

The MCP endpoint only accepts agent API keys (owl_agent_*). Client keys (owl_client_*) and JWT tokens are rejected with 401.

Permissions are enforced per-tool — if your agent key doesn't have projects:write, the create-project tool will return an error. See Authentication for details on API key permissions.

Verifying the connection

After setup, ask the agent to call the whoami tool. It should return your key type, team, and permissions:

{
  "type": "api_key",
  "key_type": "agent",
  "team": { "id": "...", "name": "My Team", "slug": "my-team" },
  "permissions": ["events:read", "projects:read", "apps:read", "..."]
}

If you see an authentication error, check that:

The key starts with owl_agent_ (not owl_client_)
The key hasn't expired
The URL points to the correct server

Ready to get started?

Connect your agent via MCP or CLI and start tracking.

Get Started GitHub