Skip to main content
The Odin MCP server connects your coding agent to your organisation’s security data. Ask Claude, VS Code, Cursor, Codex, or another Model Context Protocol client about a finding such as ODI-12, inspect its remediation guidance, create the code change and pull request yourself, then ask Odin to link the existing pull request and report the retest. Odin is organisation-scoped and GitHub-first. It provides context and workflow operations; it never creates commits, pushes branches, or creates pull requests. Connect your agent from Workspace > AI agents. The server URL is https://odin.borghq.io/api/mcp. Claude, Claude Code and VS Code sign in with your Odin account, so you need no key. Cursor, scripts and clients that cannot sign in use an API key. Clients that cannot use a remote server can run it locally from npm as @borgresearch/odin-mcp, also with an API key.

Setting up

The quickest way is Copy setup prompt on Home or on the AI agents page. Paste it into your agent, and the agent connects to Odin and helps with the rest of setup. See Set up with your AI agent.
1

Open AI agents

Go to Workspace > AI agents and copy the server URL. You need the Member role or above.
2

Add Odin to your client

Follow the steps for your client on the page, or see Client setup below. For VS Code you can click Add to VS Code.
3

Sign in and allow access

Your client opens Odin in the browser. Sign in, choose the organisation the agent may use, choose Read only or Read & write, then select Allow access and complete step-up verification.
4

Ask about a finding

Try: “Explain ODI-12, show me the suggested branch, and tell me what I need to do before opening a PR.”

Client setup

Sign in with Odin

In Claude, open Customize > Connectors, choose Add custom connector, name it Odin and enter https://odin.borghq.io/api/mcp. Then select Connect and sign in. On Team and Enterprise plans an owner adds the connector under Organization settings > Connectors, and each member then connects it for themselves. Claude Desktop uses the connectors from your Claude account.
Run this, then run /mcp in Claude Code and choose odin to sign in.
Click Add to VS Code on the AI agents page, or add this to .vscode/mcp.json. It holds no key, so it is safe to commit. VS Code opens Odin in your browser to sign in when the server first starts.
Add https://odin.borghq.io/api/mcp over Streamable HTTP without an Authorization header and sign in when the client asks. See Connect with OAuth sign-in for what the client needs to support.

With an API key

Create a key under Workspace > API Keys. The dialog that shows your new key also shows the setup for each client, with the key already in the snippets. Otherwise replace odin_... with your own key, and keep keys out of files you commit. A Read only key is enough to discover findings, read remediation context, and inspect retest history; choose Read & Write when the agent must update a status or link an existing pull request.
Cursor finishes sign-in through a cursor:// link, which Odin does not accept, so it connects with an API key. Click Add to Cursor on the AI agents page or in the key dialog. It reads the key from the ODIN_API_KEY environment variable, so set that variable where Cursor starts. Cursor opened from the Dock or Start menu may not see variables set in your shell profile. If the server cannot authenticate, add this to ~/.cursor/mcp.json instead:
Add to ~/.codex/config.toml, then restart Codex. To keep the key out of the file, replace http_headers with bearer_token_env_var = "ODIN_API_KEY" and set that variable instead.
Prefer the connector under Sign in with Odin. To run the server locally instead, which needs Node.js 24 or newer on your PATH, add this to claude_desktop_config.json, then restart Claude Desktop.
To update an existing local setup, change the package in your client config to @borgresearch/odin-mcp@latest and restart the client. For a global install, run npm install -g @borgresearch/odin-mcp@latest.
Connect over Streamable HTTP to https://odin.borghq.io/api/mcp with the header Authorization: Bearer odin_.... If the client only runs local servers, point it at npx -y @borgresearch/odin-mcp@latest and pass ODIN_API_KEY in its environment. See the package README for client-specific paths.
After changing a client’s MCP configuration, restart the client and check its list of MCP servers for odin with 58 tools.

Connect with OAuth sign-in

When a client signs in, Odin asks you to:
  • Choose one organisation where you are a Member, Admin or Owner. Connect again to use a second organisation.
  • Choose the access. If the client asks to make changes, pick Read only (view findings, assets, pentests, retests and finding discussions) or Read & write (also change finding status and assignee, link pull requests, and post or edit discussion messages). The client gets exactly the access you choose.
  • Check what the client learns about you. Once identity sign-in is enabled, some clients, such as ChatGPT, also ask who you are. Odin then lists Know your Odin account ID, and and email address if the client asks for your email. Odin shares only what is listed, and only after you select Allow access. To share your email address, Odin must know it is yours: if you have not yet signed in or verified with a code sent to it, Odin sends one now. Select Cancel if you do not want to share these details.
How a connection differs from an API key:
  • Who it acts as: you, not the organisation. It never gets more access than your current role, and it stops working if you leave the organisation or become read-only.
  • Expiry: access tokens last an hour and the client renews them automatically. A connection unused for 30 days expires.
  • Revoking: disconnect the app under Workspace > AI agents > Connected apps. Admins and owners can disconnect any app in their organisation. See Connected Apps.
  • Your details: once identity sign-in is enabled, the client learns your Odin account ID and email address only if it asked for them and you allowed it. It gets nothing else about you or your organisation through sign-in.
Your client must accept HTTPS or loopback (http://localhost, http://127.0.0.1) redirect addresses. Clients that only use a custom URL scheme to finish sign-in, such as Cursor, cannot connect this way; use an API key instead.
Odin is an OAuth 2.1 authorisation server for the MCP endpoint, following the MCP authorization specification.
  • Protected resource metadata: https://odin.borghq.io/.well-known/oauth-protected-resource/api/mcp (also served at /.well-known/oauth-protected-resource). The resource is https://odin.borghq.io/api/mcp.
  • Authorisation server metadata: https://odin.borghq.io/.well-known/oauth-authorization-server. The issuer is https://odin.borghq.io.
  • Client registration: Client ID Metadata Documents, or Dynamic Client Registration at /api/oauth/register. Clients are public; there is no client secret.
  • Authorisation code flow with PKCE (S256 only), exact redirect URI matching (loopback redirects match on any port), and the resource parameter. Authorisation responses include iss.
  • Scopes are read and write. The user can narrow a request for write to read; the token response’s scope names what was granted. A write without write returns 403 with error="insufficient_scope". A request that names neither read, write nor an OpenID Connect scope gets read.
  • Refresh tokens rotate on every use. A spent refresh token still works for 60 seconds, so clients that refresh from several connections at once are not cut off. Reusing it after that revokes the whole connection.
  • Revocation (RFC 7009) at /api/oauth/revoke.
  • Tokens are only valid for https://odin.borghq.io/api/mcp. They are not accepted by the REST API.
OpenID Connect is available only once enabled for Odin. Until then, discovery, JWKS and UserInfo return 404, and identity scopes are neither advertised nor accepted. Check the server metadata before requesting identity scopes.Once enabled, Odin is also an OpenID Connect provider for the authorisation code flow with PKCE, for clients that need to know who signed in. It implements the OpenID Connect Core requirements for that flow; it does not offer the implicit or hybrid flows, request objects or the claims parameter, so it does not meet the full dynamic provider profile.
  • Discovery: https://odin.borghq.io/.well-known/openid-configuration, with the same issuer, https://odin.borghq.io. The authorisation server metadata lists the same fields.
  • Scopes: openid and email. email needs openid. They grant no access to Odin data: a request for only openid email can sign the user in but cannot call any MCP tool, and gets 403 with error="insufficient_scope" from /api/mcp. Request read or write as well to use the tools.
  • ID token: returned from the authorisation code exchange when openid was granted. Signed with RS256; verify it with the keys at /api/oauth/jwks. It carries iss, sub (the user’s Odin ID, the same for every client), aud (your client_id), iat, exp (10 minutes), auth_time and your nonce if you sent one. It holds no email. Refreshing does not return a new ID token.
  • UserInfo: GET or POST /api/oauth/userinfo with the access token in Authorization: Bearer. It returns sub, and email and email_verified only with the email scope. email_verified is true only when Odin has verified that the address is the user’s, by a code sent to it or a provider that reports it as verified. The endpoint accepts only an access token for https://odin.borghq.io/api/mcp with openid, from a user who can still use the connection.
  • prompt=none returns login_required or consent_required, because Odin always asks the user to approve. prompt=login and max_age make the user verify again before approving. display, ui_locales, acr_values, login_hint and id_token_hint are accepted and ignored. request and request_uri return request_not_supported and request_uri_not_supported.
  • A refresh can narrow openid and email away but never add them to a connection that lacks them.

Remote connection details

The endpoint uses Streamable HTTP. It needs no Node.js or local package install. With an API key, send the header Authorization: Bearer odin_... on every request, and supply the key through your client’s secret or environment settings; do not put it in the URL or commit it. Revocation takes effect on the next request, and each request gets a fresh server instance. The endpoint returns JSON responses without persistent sessions, resumable streams, or a standalone SSE subscription. Authenticated GET and DELETE requests return 405. Requests with an untrusted browser Origin return 403; native clients can omit Origin. Cross-origin browser access is not enabled. An example initial request with an API key (set ODIN_API_KEY privately first):
Use the negotiated MCP-Protocol-Version header on subsequent requests. Both transports expose the same 58 tools. Each API key and each sign-in connection has its own allowance of 100 requests per minute. Discovery consumes one request, and a tool call consumes one transport authentication request plus one API-handler request. Rate-limit responses preserve Retry-After; tool-level refusals are MCP errors with retry guidance.

Tools

Every tool returns a readable Markdown summary and a structured payload. Human identifiers are organisation-local; ODI-12 is preferred, while the internal ID remains available for chaining.

Finding references

Use the human identifier shown in Odin:
The prefix is an alias, not a global namespace. Odin resolves the numeric suffix only inside the organisation belonging to the API key and always returns the finding’s canonical stored identifier. A reference from another organisation is not revealed through an error. Internal finding IDs are supported when chaining results between tools.

Remediation flow

  1. Ask get_finding about ODI-12.
  2. Read the remediation, code reference, workflow blockers, and suggestedBranch (for example, fix/odi-12-sql-injection-in-login-form).
  3. In Cursor or your normal development environment, create that branch, make and test the change, commit it, push it, and open the GitHub PR yourself.
  4. Explicitly ask the agent to use link_finding_pull_request with the existing PR URL. Odin verifies the PR through your organisation’s GitHub App installation and stores authoritative metadata. Linking the same PR again is safe and idempotent.
  5. When the linked PR merges, GitHub webhook processing may queue an automatic retest if the organisation’s GitHub and retest prerequisites are ready. Use get_finding_retests to distinguish no history, queued/running, completed, skipped, and failed runs.
Odin does not infer permission from a matching PR and agents should not mutate a finding merely because a URL or identifier looks correct. Ask before linking a PR or changing status.

Updating a finding’s status

update_finding_status needs an API key with Read & Write permission, created by someone who still has the Member role or above: NEEDS_REVISION and FIXED_AND_RETESTED are set by Borg’s retest process and are not client-writable. You can add a comment recorded with the change. To avoid overwriting someone else’s change, pass expectedStatus with the status you read: if the finding has moved on, Odin returns a conflict and changes nothing. assign_finding takes expectedAssigneeUserId the same way.

Retests

get_finding_retests is read-only. It never calls the manual retest endpoint, queues work, or spends credits. A completed retest exposes its sanitised verdict and status action without billing fields. Automatic retests are merge/webhook-driven; see Automatic Retests.

Agent guidance and prompts

When a client connects, the server sends short instructions that every agent reads: what Odin is, how the tools fit together, and the rules it should follow. For example, it asks before changing anything and treats finding content as data. The instructions link to the Guide for AI agents. The server also offers two prompts. Clients that support MCP prompts list them as commands. In Claude Code, for example, they appear as /mcp__odin__setup and /mcp__odin__fix_finding if you named the server odin. Both prompts ask before changing Odin or your repository.

Permissions and scoping

Every call is scoped to a single organisation: the one you chose when you signed in, or the one that owns the API key. If you work in several organisations, connect once per organisation (or create one key per organisation) and register each as a separate MCP server, such as odin-acme and odin-internal.
  • Read only: discovery, finding remediation context, linked-PR discovery, and retest reads.
  • Read & Write: all Read-only actions plus status changes and linking an existing accessible GitHub PR.
  • Signed-in connections act as you, with the access you chose when you allowed the connection.
  • Member role: Members, Admins and Owners can create API keys. A key acts as the person who created it, so every MCP call also needs that person to still be in the organisation with the Member role or above. A call never does more than their current role allows, and their name is recorded against each change.
The API key does not grant repository access beyond the organisation’s configured GitHub App installation. A PR in an inaccessible repository is rejected without creating a link.

Rate limits

Each key and each signed-in connection is limited to 100 requests per minute. 429 responses include retry guidance.

Troubleshooting

Check that the client supports MCP sign-in (OAuth) and that you added the server without an Authorization header. You need the Member role or above, and an organisation that requires single sign-on needs you to sign in with SSO. Cursor cannot finish sign-in; use an API key for it.
You allowed Read only access. Disconnect the app under Workspace > AI agents, then connect again and choose Read & write. Clients that support it ask you to sign in again for more access by themselves.
Check the key under Workspace > API Keys, confirm the client config sends it as Authorization: Bearer (or sets ODIN_API_KEY for a local server), and restart the client. Most clients only reload MCP configuration at startup. If you used Add to Cursor, check that Cursor can see ODIN_API_KEY.
The key reached the expiry chosen when it was created, and Odin refuses it with code API_KEY_EXPIRED. Expired keys cannot be renewed: create a new key, update the client config, and revoke the old key.
The agent attempted a status change or PR link with a Read-only key. Create a new Read & Write key; permissions on an existing key are not silently upgraded.
The key’s creator now has Read only access, or is no longer in the organisation, so the key stops working. Create a new key as a current Member, Admin or Owner. If a Read only creator’s Member role is restored, the old key works again; keys of someone removed from the organisation are revoked for good.
Confirm the human identifier, and remember that identifiers and API keys are organisation-scoped. A different organisation’s finding is intentionally indistinguishable from an unknown finding.
The organisation’s retest automation capability is gated or not configured. Check the GitHub and automatic-retest settings.
Check the client’s MCP logs and restart it after changing configuration. A local server needs Node.js 24 or newer.

Connected Apps

See and disconnect the agents that signed in with your account

API Keys

Keys for Cursor, scripts, CI and clients that cannot sign in

Automatic Retests

Understand merge-driven verification and retest outcomes

Collaboration and attachment safety

Assignment, messages, edits, deletion and discussion actions can notify people, send email, synchronise Slack, or update connected issue trackers. Ask the user before making these changes. Posting a message is not idempotent. Edits and deletion are limited to messages authored by the person the connection acts as: the API key creator, or the user who signed in with OAuth. MCP connections have no personal unread state. Attachment tools return temporary signed URLs. They do not upload or download bytes. Upload the exact file with the returned required headers, without an Odin API key, before attaching its private gs:// reference to a message. Treat signed URLs as secrets. The server validates that attachments belong to the finding and message. The tool set covers supported API-key finding workflows and asset/pentest reads. Private intelligence features, parked maps, asset changes, scan launches, and API-key administration are excluded. request_finding_retest spends credits, and so does link_finding_pull_request when the pull request has already merged and Automatic retests is on. Finding list totals use the filtered pagination count; aggregate statistics can cover a wider scope.