Setup

Prerequisites

You need an agent API key (owl_agent_*) to connect. A default agent key is automatically created when you sign up — sign in below to see it pre-filled in all editor configs.

Endpoint URL

Editor Setup

Pick your editor below for copy-pasteable config. We support Claude Code, Codex, OpenCode, Cursor, VS Code, Claude Desktop, Windsurf, Zed, JetBrains (IntelliJ, WebStorm, PyCharm, etc.), Cline, and Roo Code.

Other MCP Clients

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

• Transport: Streamable HTTP (stateless JSON)
• URL: https://api.owlmetry.com/mcp
• Auth: Authorization: Bearer owl_agent_YOUR_KEY_HERE header (required on POST and GET)
• Mode: Stateless JSON — each POST request is independent, no session initialization needed. GET opens an authenticated SSE stream; DELETE returns 405.

MCP Resources

In addition to the tool surface, the server exposes one MCP resource that clients can read on connection:

Supported clients read the guide automatically so agents understand how to use the tools effectively. SDK integration guides live in a separate Claude Code plugin marketplace — install inside Claude Code with /plugin marketplace add owlmetry/owlmetry-skills.

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:

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