MCP server
Hyrax runs a Model Context Protocol (MCP) server so the AI coding agents you already use — Claude Code, Cursor, Copilot — can query your repositories' live findings, rules, and suggestions over HTTP. Reach for it when the answer changes often: What findings are open on this file? Which suggestions are still pending? What rules apply before I edit this file?
Connecting
The server is mounted at /mcp over streamable HTTP — point your client at /mcp/ with the trailing slash. On the API host a bare POST /mcp 307-redirects to it, preserving method and body, but a client that doesn't follow 307s will fail — and on the app host the bare path doesn't route at all, so always include the slash. Use the same hk_live_ API key as the REST API, passed as a bearer token:
POST /mcp/ HTTP/1.1
Authorization: Bearer hk_live_...
Content-Type: application/json
The endpoint is rate-limited per API key — about 60 requests per minute. Exceed it and you get a 429 with a Retry-After header. If the key carries a dollars_per_hour ceiling, note that on MCP it gates every call, reads included — the server is a single JSON-RPC endpoint, so it can't price per tool the way the REST routes do.
A key's restrictions travel with it across transports: if the key was minted with an IP allowlist (allowed_cidrs), the MCP server enforces it exactly as the REST API does — a request from outside every listed range (or whose client IP can't be reliably established) is refused with a 401, fail-closed.
The MCP server authenticates with the same API keys as the REST API, included on both plans, Free and Paid. See the API overview and Plans & pricing.
What you can do
Every per-repository tool addresses your repo by the owner/repo/branch triple. An agent typically lists your repos first, then passes the triple into the rest.
Read tools query your repo's live state and never change anything:
| Tool | What it answers |
|---|---|
| List repositories | Which repos does this workspace have? |
| Repository overview | The stack profile, domain summary, and engineering principles for one repo. |
| Read knowledge bundle | The full discovery bundle — profile, principles, conventions, and open directives. |
| List / search observations | The findings + suggestions list, filtered by kind, status, priority, and repo; or a substring search (with an optional kind filter). |
| Applicable rules | The conventions and skills that apply to a specific file path. |
| Canonical pattern | The repo's canonical patterns.md prose (optionally filtered by an area keyword) — the same content Hyrax publishes to .hyrax/discovery/, served live so you never read a stale skill file. Requires the view_repositories scope. |
| Recent issues | Open observations touching a given file path. |
| Explain an observation | The full body of one observation by its HYRAX-N ref. |
| Pending migrations | The open architectural suggestions feed. |
| How-to guides | The list of published how-to guides, and the body of any one. |
| Cost forecast | The likely cost and duration band (low / mid / high, with sample size and confidence) for a workflow on a repo — readable by any key, so a submit-only key can quote the price before it runs. |
| Job status | The state, workflow, repo, timestamps, error, failure classification, and fix PR URL for a job you submitted. Requires the view_jobs scope. |
| List jobs | A repo's jobs, newest first, with an optional status filter — the same slim per-job shape as Job status, for when you don't hold a job id. Requires the view_jobs scope. |
| List fix PRs | The per-repo lane of findings Hyrax opened a fix PR for — ref, title, PR link, and a derived status (merged answers "did my fix land?"; in_review / revising mean the PR is still open). Findings with an open fix PR leave the active observations list and surface here. Requires the view_repositories scope. |
Write tools run without round-tripping through the web app. Every tool — read and write — is gated by the key's scopes, including for account owners: a key's scopes are a hard ceiling for that key on every surface (REST and MCP alike), so a call is refused unless the key carries the matching scope even when its owner is the account owner. If a key lacks the scope it needs, mint a new key with the fuller set, since keys only narrow after mint.
Cost-bearing writes submit or drive a job and draw on your spend controls exactly as the REST routes do:
| Tool | What it does | Required scope |
|---|---|---|
| Submit a job | Start a workflow run (audit, and so on) for a repo. | submit_audit_jobs, plus submit_fix_jobs for a fix or submit_task_jobs for a task — the key needs both the baseline and the workflow scope |
| Submit a fix | Spawn a fix job for one finding (HYRAX-N ref) — mints the job and registers the fix attempt in one call. | submit_fix_jobs |
| Request a fix | Confirm or re-bind the fix attempt for an already-minted fix job (takes the ref plus that job's id — it does not spawn the job). | submit_fix_jobs |
| Retry a job | Re-submit a failed or cancelled job, preserving its workflow. | submit_audit_jobs, plus the original workflow's scope for fix / task retries (both on the key) |
| Register a repository | Add a repository to the workspace. | manage_repos |
Triage writes take routine, reversible actions on findings and settings:
| Tool | What it does | Required scope |
|---|---|---|
| Dismiss an observation | Close an observation with a reason (false positive, won't fix). | triage_observations |
| Acknowledge an observation | Stamp an observation as seen (acknowledged_at) — it stays open on the worklist. | triage_observations |
| Complete an observation | Mark an observation addressed when it was resolved outside a Hyrax PR (optional proof link + note). Reversible via reopen. | triage_observations |
| Reopen an observation | Move a closed observation back to new. | triage_observations |
| Create a ticket | File a Linear ticket for an observation (when the repo has ticket integration configured). | triage_observations |
| Update repository metadata | Flip safe repo settings, such as enabling PR review. | manage_repos |
| Set guidance / context | Upsert or clear a guidance slot, or set workspace-wide context the agents read. | manage_tenant_settings |
| Set / clear a tenant setting | Set or clear a typed workspace configuration knob (e.g. audit_timeout_s); clearing reverts the knob to its default. | manage_tenant_settings |
| Set learning flags | Toggle the workspace self-improvement setting (learn_mode). | manage_tenant_settings |
| Record a discovery-doc read | Telemetry callback: note that the agent just opened a published .hyrax/discovery/ document (repo triple + relative doc path), so future discover runs keep the docs agents actually use. | none — telemetry only |
REST-only. Destructive actions stay out of MCP — reach for the REST API for:
- Cancelling a job
- Deleting or resetting a repository
- Webhook subscription management
Prompts
The server also ships three MCP prompts — ready-made instructions your client's model can load. In Claude Code they surface as slash-commands (/mcp__hyrax__<prompt>); other MCP clients list them under prompts.
| Prompt | Arguments | What it loads |
|---|---|---|
hyrax_agent_loop | — | The operating guide for an agent driving Hyrax autonomously: the forecast → submit → poll → read → fix loop, cost safety, scopes, and pagination. |
triage_new_findings | org, repo, branch | Triage a repo's new findings: group by priority and kind, propose fix / dismiss / acknowledge per finding, and ask before any cost-bearing call. |
investigate_finding | org, repo, branch, ref | Deep-dive one observation by its HYRAX-N ref: pull its full body, gather context, and summarize root cause + proposed remedy. |
For example, /mcp__hyrax__triage_new_findings with org=myorg repo=myrepo branch=main starts a guided triage session against that repo's open findings.
Setting up a client
Any MCP client that speaks streamable HTTP with a bearer header can connect. In Claude Code, add an HTTP MCP server entry (Cursor and others use the same fields):
{
"mcpServers": {
"hyrax": {
"type": "http",
"url": "https://api.hyrax.dev/mcp/",
"headers": { "Authorization": "Bearer hk_live_REPLACE_ME" }
}
}
}
The canonical endpoint is on the API host (api.<domain>). The app host also forwards /mcp/ to the same origin, so an existing https://app.hyrax.dev/mcp/ URL keeps working — but point new clients at the API host.
Verify the key before wiring an agent up by listing the tools directly:
curl -sS https://api.hyrax.dev/mcp/ \
-H 'Authorization: Bearer hk_live_REPLACE_ME' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
The response enumerates every tool with its input schema.
MCP vs published discovery files
MCP and the published discovery bundle are complementary:
- Reach for MCP when the answer changes often — open observations, pending suggestions, the latest audit's results — or when the question is about a specific file ("what applies to this path?").
- Reach for the published files when the agent needs offline access, or when your
CLAUDE.mdand editor rules must point at a stable in-repo path.
An agent that reads .hyrax/discovery/ files gets the same knowledge the MCP server serves.
See also
- API overview — keys, auth, and the REST surface.
- Findings & suggestions — the observation model the MCP tools query.