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
Open AI agents
Add Odin to your client
Sign in and allow access
Ask about a finding
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
Claude and Claude Desktop
Claude and Claude Desktop
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.Claude Code
Claude Code
/mcp in Claude Code and choose odin to sign in.VS Code
VS Code
.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.Other clients that support MCP sign-in
Other clients that support MCP sign-in
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 replaceodin_... 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
Cursor
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:Codex
Codex
~/.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.Claude Desktop, running Odin locally
Claude Desktop, running Odin locally
PATH, add this to claude_desktop_config.json, then restart Claude Desktop.@borgresearch/odin-mcp@latest and restart the client. For a global install, run npm install -g @borgresearch/odin-mcp@latest.Windsurf, Cline, and others
Windsurf, Cline, and others
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.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.
- 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.
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.
For client developers
For client developers
- Protected resource metadata:
https://odin.borghq.io/.well-known/oauth-protected-resource/api/mcp(also served at/.well-known/oauth-protected-resource). The resource ishttps://odin.borghq.io/api/mcp. - Authorisation server metadata:
https://odin.borghq.io/.well-known/oauth-authorization-server. The issuer ishttps://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 (
S256only), exact redirect URI matching (loopback redirects match on any port), and theresourceparameter. Authorisation responses includeiss. - Scopes are
readandwrite. The user can narrow a request forwritetoread; the token response’sscopenames what was granted. A write withoutwritereturns403witherror="insufficient_scope". A request that names neitherread,writenor an OpenID Connect scope getsread. - 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 for client developers
OpenID Connect for client developers
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:
openidandemail.emailneedsopenid. They grant no access to Odin data: a request for onlyopenid emailcan sign the user in but cannot call any MCP tool, and gets403witherror="insufficient_scope"from/api/mcp. Requestreadorwriteas well to use the tools. - ID token: returned from the authorisation code exchange when
openidwas granted. Signed withRS256; verify it with the keys at/api/oauth/jwks. It carriesiss,sub(the user’s Odin ID, the same for every client),aud(yourclient_id),iat,exp(10 minutes),auth_timeand yournonceif you sent one. It holds no email. Refreshing does not return a new ID token. - UserInfo:
GETorPOST /api/oauth/userinfowith the access token inAuthorization: Bearer. It returnssub, andemailandemail_verifiedonly with theemailscope.email_verifiedistrueonly 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 forhttps://odin.borghq.io/api/mcpwithopenid, from a user who can still use the connection. prompt=nonereturnslogin_requiredorconsent_required, because Odin always asks the user to approve.prompt=loginandmax_agemake the user verify again before approving.display,ui_locales,acr_values,login_hintandid_token_hintare accepted and ignored.requestandrequest_urireturnrequest_not_supportedandrequest_uri_not_supported.- A refresh can narrow
openidandemailaway 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 headerAuthorization: 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):
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:Remediation flow
- Ask
get_findingaboutODI-12. - Read the remediation, code reference, workflow blockers, and
suggestedBranch(for example,fix/odi-12-sql-injection-in-login-form). - 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.
- Explicitly ask the agent to use
link_finding_pull_requestwith 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. - 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_reteststo distinguish no history, queued/running, completed, skipped, and failed runs.
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.
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 asodin-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.
Rate limits
Each key and each signed-in connection is limited to 100 requests per minute.429 responses include retry guidance.
Troubleshooting
The client cannot sign in to Odin
The client cannot sign in to Odin
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.The agent cannot change a finding after signing in
The agent cannot change a finding after signing in
ODIN_API_KEY is not set or invalid
ODIN_API_KEY is not set or invalid
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.ODIN_API_KEY has expired
ODIN_API_KEY has expired
API_KEY_EXPIRED. Expired keys cannot be renewed: create a new key, update the client config, and revoke the old key.API key does not have write permission
API key does not have write permission
The person who created this API key is no longer a member
The person who created this API key is no longer a member
Finding not found
Finding not found
The server starts but no tools appear
The server starts but no tools appear
Connected Apps
API Keys
Automatic Retests
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 privategs:// 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.