MCP & agents

Okapi mounts an MCP server over HTTP at /mcp, inside the same running instance as everything else — there's no separate process to start and no stdio transport. One transport, one auth model, identical on self-host and cloud: point an agent at your instance's /mcp endpoint with an agent token, and it can do everything the dashboard's Issues/Logs/Releases pages can, scoped to whatever that token is allowed to see. Agents are never metered and never gated to a paid tier — the whole MCP surface ships in every edition, every plan.

Client configuration¶

Add Okapi as an HTTP MCP server with a Bearer token. Claude Code, Cursor, and Codex all support this shape:

# Cloud
claude mcp add okapi --transport http https://cloud.useokapi.app/mcp \
  --header "Authorization: Bearer okapi_agent_…"

# Self-host
claude mcp add okapi --transport http https://your-okapi-host/mcp \
  --header "Authorization: Bearer okapi_agent_…"

Self-host and cloud differ only in hostname — same transport, same tools, same token format. The documented default is a project-scoped token in a per-repo .mcp.json, so each codebase talks to exactly its own Okapi project; mint a broader organization-wide token only when an agent genuinely needs to work across projects (e.g. provisioning a new one).

Minting a token¶

Dashboard: Settings → Agent tokens (organization settings, owner-only) → New token. Give it a name, a role, and — optionally — narrow it to one project. The plaintext is shown once, alongside a ready-to-paste claude mcp add command with the token already filled in.

CLI, for headless self-host operators or CI:

okapi createtoken --role triage
okapi createtoken --role read --project web-app --name ci

--project <slug> scopes the token to one project; omitted, the token is organization-wide. On a self-host instance (exactly one organization) the organization resolves automatically; on an instance with more than one organization, pass --organization <slug> or the command errors with that instruction. The plaintext and the inline claude mcp add command print once — there's no second chance to retrieve either.

Roles¶

Three capability tiers, checked on every tool call:

A token can be revoked at any time from Settings → Agent tokens; revocation is immediate and irreversible (mint a new one to replace it).

Tools¶

• whoami — the token's own name, scope (organization-wide or one project), role, and rate-limit state, so an agent can discover its own permissions without probing for a 403.
• list_projects — every project the token can see (all of them for an organization-wide token; just its own for a project-scoped one).
• list_issues — list issues in a project; filter by status (unresolved default, all, resolved, ignored, snoozed), level, or a title query.
• whats_new — what changed since a release or a recent time window: new issues, regressions, and spiking issues. The natural first call in a debugging session.
• get_issue_context — the one-shot fix bundle for an issue by short id: a symbolicated stacktrace, breadcrumbs, trace-id-correlated logs, release info, a daily frequency series, affected-user count and sample contexts, similar issues, and the raw event payload.
• check_resolution — did a previous single-issue resolve hold? Compares fresh events against the marker stamped when update_issue resolved it.
• update_issue — triage by short id: resolve, unresolve, ignore, snooze (with snoozeMinutes), or delete (requires the admin role and a confirmDelete: true flag). resolve also accepts an optional commit/release and note.
• bulk_update_issues — apply one triage action to every issue matching a filter (status/level/query), not just an explicit list — resolve, unresolve, ignore, snooze, or delete (requires admin and confirmBulk: true).
• search_logs — search a project's logs by level, message query, traceId, attributes, or a sinceMinutes time window.
• create_project — provision a brand-new project and mint its default DSN key in one call. Requires an organization-wide admin token.
• get_dsn — read a project's DSN (the SDK init string). Requires an admin token, the same sensitivity as the dashboard's owner-only DSN Keys page.
• verify_installation — is Okapi actually receiving events for this project? Reports whether a DSN key exists, whether any event has arrived, and whether it was a real error or just the synthetic "Send a test event" payload.

Every tool call is scoped to the token's organization (and project, if it's project-scoped) — a token can never reach another organization's data, and a read-role token can never mutate anything. Event- and log-derived text (messages, stack frames, breadcrumbs, correlated logs, release names, the raw payload) returned by these tools is wrapped in an explicit untrusted-data envelope before it reaches an agent: it's captured application data, never instructions.

Agent bootstrap¶

An agent arriving at a running instance with no prior context starts at GET /api/v1/agents: a public, ungated JSON manifest describing how to authenticate (no session, no credential granted), the three roles and what each grants, recommended first calls (whoami → list_projects → whats_new / verify_installation), and doc links. Its tool catalog is generated from the same registry the instance's live /mcp endpoint runs, so it can't drift from what's actually callable.

Once an agent knows which project it's wiring up, GET /api/v1/organizations/{organizationSlug}/projects/{projectSlug}/install/{node|python|browser}.md serves a DSN-personalized install guide — any organization member may fetch it — so it can install the SDK, initialize it against the real DSN, send a test event, and confirm over verify_installation rather than eyeballing the dashboard.

Agent Kit ships two skills, served as plain markdown from the instance — GET /api/v1/agents/skills/okapi-setup.md and GET /api/v1/agents/skills/okapi-fix-issues.md — encoding the setup loop (detect stack → install → initialize → test event → verify_installation, then mint a per-repo triage token) and the debugging loop (whats_new → bulk-suppress noise → get_issue_context per issue → fix → check_resolution → resolve-in-commit). There's no installer: an agent fetches the markdown and places it itself — .claude/skills/<name>/SKILL.md for Claude Code, the Cursor rules directory, or a fragment appended to AGENTS.md for Codex.

For AI agents¶

If you're an agent reading this because a human pointed you at an Okapi instance: don't scrape the dashboard UI or ask for a pasted stack trace. Connect over MCP and work from the real data instead —

1. whoami to confirm your own scope and role, then list_projects.
2. whats_new or list_issues (default unresolved) to see what's actually open.
3. get_issue_context for the full fix bundle on anything you're investigating.
4. search_logs to pull structured logs correlated by trace id or time window around an error.
5. update_issue or bulk_update_issues to resolve, snooze, or ignore once you've verified a fix — don't leave triage to the human if you've already confirmed the fix landed.

A machine-readable summary of Okapi — what it is, pricing, and where these docs live — is published at /llms.txt.

Next: Telemetry for what an Okapi instance sends home on its own, independent of anything you do with MCP.