@borgresearch/odin-mcp

Model Context Protocol server for the Odin security platform by Borg. Lets coding agents query findings, pentests, and attack-surface assets — and transition findings between in-progress states — directly from your editor or chat tool.

Prerequisites

• Node.js 22 or newer.
• An Odin account with at least one organisation.
• An Odin API key (see Quick start). read permission is enough for every tool except update_finding_status, which needs write plus the member role.

Quick start

1. Create an API key. Sign in to https://odin.borghq.io, open Management > API Keys, click Create key, and pick the permissions you need (read, or read + write if you want the agent to update findings). Copy the full key — it is shown once.
2. Add the server to your client. Pick your tool below and paste the JSON snippet. Replace odin_... with the key you just copied.
3. Verify. Restart the client, list its connected MCP servers, and confirm odin appears with the seven tools listed in Tools. A first prompt like "List my critical findings from the latest pentest" should return real data.

ODIN_API_KEY=odin_... npx @borgresearch/odin-mcp

You can also install globally:

npm install -g @borgresearch/odin-mcp
ODIN_API_KEY=odin_... odin-mcp

Configuration

| Variable | Required | Notes | |----------|----------|-------| | ODIN_API_KEY | yes | API key with at least read permission. write is required for update_finding_status. |

Each call sends Authorization: Bearer ${ODIN_API_KEY}. Keys are organisation-scoped; if you belong to multiple organisations, create one key per organisation and run a separate MCP server entry for each.

Tools

All tools accept a single JSON object and return both a markdown summary (for the agent to read) and a structured payload (for the agent to act on).

| Name | Permission | Description | |------|------------|-------------| | list_findings | read | List findings, optionally filtered by pentest, asset, severity, status, or search term. Paginated. | | get_finding | read | Fetch a single finding with its latest revision (summary, description, impact, details, remediation, affected assets). | | update_finding_status | write, member role | Transition a finding to MITIGATING (you are working on the fix) or OPEN_FOR_RETEST (the fix is ready). | | list_pentests | read | List all pentests for the organisation, with status and scheduled window. | | get_pentest | read | Fetch a single pentest with status, schedule, and in-scope targets. | | list_assets | read | List attack-surface assets, optionally filtered by type, source, dynamic status, or search term. Paginated. | | get_asset | read | Fetch a single asset with the findings that reference it in their latest revision. |

Tool parameters and examples

list_findings

pentestId?, assetId?, severity? (CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL), status?, search?, sortBy? (severity | createdAt), sortOrder?, limit? (1–200, default 50), offset?.

"Show me the open critical and high findings from pentest p_abc123." "Search my findings for anything mentioning S3."

get_finding

findingId (required).

"What are the remediation steps for finding f_abc123?"

update_finding_status

findingId (required), status (MITIGATING | OPEN_FOR_RETEST).

"I've started working on f_abc123, mark it as mitigating." "I've fixed f_abc123, mark it ready for retest."

Other transitions (RESOLVED, ACCEPTED_RISK, etc.) are reserved for the operations team and are intentionally not writable from the API.

list_pentests / get_pentest

list_pentests takes no parameters. get_pentest requires pentestId.

"What's in scope for pentest p_xyz?" "List all my pentests scheduled this quarter."

list_assets

type? (DOMAIN | SUBDOMAIN | IP | URL | WILDCARD), source? (MANUAL | RECON | IMPORT | AGENT), status?, search?, sortBy?, sortOrder?, limit? (1–100, default 50), offset?.

"List subdomains discovered by recon." "Which manually added domains are currently down?"

get_asset

assetId (required).

"Summarise findings affecting api.example.com and group them by severity."

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "odin": {
      "command": "npx",
      "args": ["-y", "@borgresearch/odin-mcp"],
      "env": {
        "ODIN_API_KEY": "odin_..."
      }
    }
  }
}

Use with Claude Code

claude mcp add odin --env ODIN_API_KEY=odin_... -- npx -y @borgresearch/odin-mcp

Use with Cursor

Open Settings > MCP and add a new server, or add the following to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "odin": {
      "command": "npx",
      "args": ["-y", "@borgresearch/odin-mcp"],
      "env": {
        "ODIN_API_KEY": "odin_..."
      }
    }
  }
}

Use with Windsurf

Add the following to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "odin": {
      "command": "npx",
      "args": ["-y", "@borgresearch/odin-mcp"],
      "env": {
        "ODIN_API_KEY": "odin_..."
      }
    }
  }
}

Use with VS Code (GitHub Copilot)

Add the following to your project's .vscode/mcp.json:

{
  "servers": {
    "odin": {
      "command": "npx",
      "args": ["-y", "@borgresearch/odin-mcp"],
      "env": {
        "ODIN_API_KEY": "odin_..."
      }
    }
  }
}

Use with Cline

Open Settings > MCP Servers > Edit MCP Settings and add:

{
  "mcpServers": {
    "odin": {
      "command": "npx",
      "args": ["-y", "@borgresearch/odin-mcp"],
      "env": {
        "ODIN_API_KEY": "odin_..."
      }
    }
  }
}

Troubleshooting

ODIN_API_KEY is not set or invalid — the environment variable is missing or the key has been revoked. Confirm the key still exists at Management > API Keys and that your client config sets env.ODIN_API_KEY. Most clients require a full restart after editing config files.

API key does not have write permission — the call was update_finding_status but the key only has read. Create a new key with both read and write, or ask an admin to do it for you.

Finding not found — the finding ID does not belong to the organisation the API key is scoped to. Keys are organisation-scoped; if you have multiple organisations, create one key per organisation and configure them as separate MCP servers (e.g. odin-acme, odin-personal).

Rate limit exceeded. Try again in N seconds — the API allows 100 requests per minute per key. The error message includes the wait time. If you hit this often, batch your queries (use list_findings with filters instead of many get_finding calls).

The server starts but no tools appear in the client — check the client's MCP logs. Most clients require Node.js 22+ on PATH; verify with node --version. If you use nvm or fnm, your client may not pick up the active version — point command at an absolute path to a Node 22 binary.

Inspecting tool calls locally — clone the borg-platform repo, run pnpm build then pnpm inspect from frontend/packages/odin-mcp to launch the MCP Inspector against your local build.

License

UNLICENSED. This package is published for use with the Odin platform; redistribution is not permitted.