Connect via MCP

Connect to Subimage via Model Context Protocol (MCP)

Subimage's HTTP MCP server connects AI assistants like Claude Code and Codex CLI to your security data with OAuth authentication.

Subimage HTTP MCP Server

The Subimage HTTP MCP server provides AI assistants with secure access to Subimage's full API, including findings, rules, inventory, and graph queries. It uses the same authentication and authorization as the web application.

Features

  • Full API Access: Query findings, rules, inventory, and infrastructure graph
  • Role-Based Access Control: Respects your organization's member/operator/admin roles
  • OAuth Authentication: Uses WorkOS AuthKit for secure single sign-on
  • M2M Token Support: Automate workflows with machine-to-machine tokens

MCP Server URL

Your tenant-scoped Subimage MCP server is available at:

<MCP_URL>

Prefer this direct tenant endpoint when configuring an MCP client. Marketplace integrations may use https://app.subimage.io/mcp, which resolves the tenant from the authenticated WorkOS organization.

Authentication Methods

Subimage MCP supports two authentication methods:

A. OAuth Authentication (For Interactive Use)

OAuth authentication uses your Subimage login credentials and respects your organization membership and role (member, operator, or admin).

Setup for Claude Code:

claude mcp add --transport http subimage <MCP_URL>

Setup for Codex CLI:

codex mcp add subimage --url <MCP_URL>

When you first use the MCP server, you'll be prompted to authenticate via your web browser. The CLI will open your browser to complete the OAuth flow.

Sign in without a browser on the same machine

Subimage supports OAuth 2.0 device authorization (RFC 8628), so agents and CLIs that run where no browser can open, such as an agent on a server, sign in as a user with their own role. The client shows a link and a code. Open the link on any device, sign in, check that the code matches, choose your organization, and then click Allow. The client then has a token for <MCP_URL>.

If you're building the client yourself, use these endpoints on Subimage's authorization server, https://auth.subimage.io. It also publishes them at /.well-known/oauth-authorization-server.

  1. Register your client once. Include the device grant and refresh_token. A loopback redirect URI is enough, since the device flow doesn't use it:

    curl -s https://auth.subimage.io/oauth2/register \
      -H 'Content-Type: application/json' \
      -d '{
        "client_name": "My agent",
        "redirect_uris": ["http://127.0.0.1/callback"],
        "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
        "token_endpoint_auth_method": "none"
      }'

    Save the client_id from the response.

  2. Request a device code:

    curl -s https://auth.subimage.io/oauth2/device_authorization \
      -d client_id=CLIENT_ID \
      --data-urlencode 'scope=openid profile email offline_access'

    Show the user verification_uri_complete, or verification_uri and user_code.

  3. Poll for the token every interval seconds until the user approves:

    curl -s https://auth.subimage.io/oauth2/token \
      -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
      -d client_id=CLIENT_ID \
      -d device_code=DEVICE_CODE

    While the response is authorization_pending, keep polling. On slow_down, add five seconds to the interval. Stop when the code reaches expires_in.

  4. Send the access_token to <MCP_URL> in an Authorization: Bearer header. It's valid for 12 hours. Before it expires, request a new one with grant_type=refresh_token, your client_id, and the refresh_token.

Replace CLIENT_ID with the client_id from step 1, and DEVICE_CODE with the device_code from step 2.

B. M2M Token Authentication (For Automation)

Machine-to-machine (M2M) tokens are ideal for automation, CI/CD pipelines, or non-interactive workflows. M2M tokens can be scoped to specific roles (member, operator, admin).

Please see the M2M Authentication documentation for more information: M2M Authentication

M2M Token Best Practices:

  • Use member role tokens for read-only automation
  • Use operator role tokens for rule management workflows
  • Rotate client secrets from the Subimage API page after suspected exposure or according to your organization's policy
  • Store client secrets in environment variables or a secrets manager
  • Never commit client secrets or access tokens to version control

Available Tools

Once connected, your AI assistant has access to the following tools. The server only lists the tools your role is allowed to call.

Getting Started

Tool Description
subimageReadMe Return the tool guide, routing rules, tenant context, and the skill catalog. Agents call this first
loadSubImageSkill Fetch one Subimage skill's full instructions by name

Security Findings & Compliance

Tool Description
subimageListRules List rule summaries with findings counts and last-run health, or full tenant-authored definitions with view="custom_definitions"; exec_status="ERROR" lists failing rules
subimageCreateCustomRule Create a custom Cypher rule. The call runs the draft the way the findings sync will and refuses it when a query would fail (operator role or above). See Custom Rules
subimageUpdateCustomRule Replace an existing custom rule's definition. The same check runs, and the call is refused when a query would fail (operator role or above)
subimageGetRuleHistory Page through a rule's archived (remediated) findings
subimageListFrameworks List compliance frameworks (CIS AWS, CIS GCP, etc.) with enabled status
subimageGetFrameworkHistory Get compliance history snapshots showing score trends over time

Vulnerability Management

Tool Description
subimageListVulnerabilityActionItems List remediation action items, one per affected service image, with summary fix text and CVE, package, and image counts
subimageGetVulnerabilityActionItem Get one action item's full remediation plan (keyed by its service image): ordered fix steps, affected CVEs, packages, and impacted images

CVEs and packages are Signal nodes in the graph. Query them with subimageRunCypher; the signals-via-cypher skill carries the label model and query shapes.

Attack Path Discovery

Tool Description
subimageGetScenarioCapabilities Get valid attacker capabilities for a node type (for what-if scenarios)
subimageCreateAttackPathScenario Create a what-if scenario to simulate attacker capabilities on resources

Discovered attack paths are Signal nodes in the graph, read with subimageRunCypher via the signals-via-cypher skill.

Issues

Tool Description
subimageListIssues List issues in the queue with priority, state, and owners
subimageGetIssue Get detail for one issue: signals, triage vector, action items, and timeline. A large issue returns its open signals first and its newest timeline entries, with the totals in truncation
subimageUpdateIssue Assign or replace issue owners, or snooze an issue until a date or indefinitely
subimageOverrideIssueTriageVector Override an issue's triage vector

Cloud Inventory

Tool Description
subimageEnrichIp Attribute a public IP with third-party IP intelligence: ownership, geolocation, and VPN, proxy, Tor, or datacenter signals

Listing, counting, and filtering resources runs through subimageRunCypher: each resource type is one ontology label in the graph. Load the inventory-via-cypher skill and it maps the type you asked for to its label and query shape. Because it reads the graph directly, it covers any resource type present, not a fixed list.

Graph Query & Schema

Tool Description
subimageListModules List all data source modules (AWS, GCP, GitHub, etc.) with sync status
subimageListModuleSchemaNodes List node types from a module's schema with descriptions
subimageGetNodesSchema Get complete schema (properties, relationships, supporting modules, parallel labels) for one or more labels (resolves ontology aliases)
subimageRunCypher Execute read-only Cypher queries against the Neo4j graph database
subimageSearchModelQueries Search saved Cypher queries that match the given node labels
subimageSaveModelQuery Save a working Cypher query for future reuse

Example Usage

Here are example prompts you can use with your AI assistant once connected to Subimage:

Security Posture

  • "Show me all security rules that have findings"
  • "Which rules are currently disabled and why?"
  • "List the top 10 rules with the most findings"
  • "What custom rules has my team created?"

Vulnerability Management

  • "List all critical CVEs affecting my infrastructure"
  • "Show me CVEs with known exploits (CISA KEV)"
  • "What packages can I update to fix the most vulnerabilities?"
  • "Give me details on CVE-2024-3094: what resources are affected?"
  • "How many vulnerabilities can be fixed by updating base images?"

Attack Path Analysis

  • "What attack paths exist in my environment?"
  • "Show me the details of the most critical attack path"
  • "Are there any attack paths involving my S3 buckets?"
  • "What would happen if an attacker gained access to my production EC2 instances?"
  • "Run a what-if scenario: what if someone compromised our public-facing load balancer?"

Cloud Inventory

  • "List all my containers and their health status"
  • "Show me all public S3 buckets"
  • "Which compute instances are running in us-east-1?"
  • "List all service accounts across all providers"
  • "Show me certificates expiring soon"
  • "Find users without MFA enabled"

Compliance

  • "Which compliance frameworks are enabled for my organization?"
  • "Show me the CIS AWS compliance score trend over the last 30 days"
  • "How has our compliance posture improved this quarter?"

Graph Queries

  • "How many EC2 instances are exposed to the internet?"
  • "List all AWS accounts in the graph"
  • "Find all RDS instances that are not encrypted"
  • "Show me the schema for GCP node types"
  • "What data sources are configured and when did they last sync?"

Setup Guides by Client

Below are instructions for configuring the Subimage MCP server in popular AI tools. In all cases, your MCP server URL is:

<MCP_URL>

Claude Code

Run this command in your terminal:

claude mcp add --transport http subimage <MCP_URL>

Then launch Claude Code with claude. You'll be prompted to authenticate via your browser on first use.

Claude Desktop / Claude.ai

The Subimage MCP server uses Streamable HTTP transport. In Claude Desktop and Claude.ai, remote Streamable HTTP servers are configured as Custom Connectors. claude_desktop_config.json is stdio-only and won't work for this server.

Only the org Owner can add custom connectors to the org catalog. Once added, each member connects their own account.

  1. As the Owner, go to Organization Settings > Connectors
  2. Click Add custom connector
  3. Set the Name to SubImage
  4. Set the Remote MCP server URL to <MCP_URL>
  5. Members then go to Settings > Connectors, find Subimage, and click Connect to authenticate

Only users who have been added to your Subimage tenant on the Team settings page can authenticate; the connector signs in with your Subimage account, so members without one will be blocked at the OAuth step.

Cursor

  1. Open Cursor > Settings > Cursor Settings > Tools & MCPs
  2. Click New MCP Server. Your .cursor/mcp.json should open. Enter:
{
  "mcpServers": {
    "subimage": {
      "type": "streamableHttp",
      "url": "<MCP_URL>"
    }
  }
}
  1. The subimage MCP server should be listed. Click Connect to authenticate.

VS Code / GitHub Copilot

  1. Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
  2. Select MCP: Add Server
  3. Choose HTTP
  4. Enter the URL: <MCP_URL>
  5. Name it subimage

Codex CLI

Run this command in your terminal:

codex mcp add subimage --url <MCP_URL>

Then launch Codex with codex. You'll be prompted to authenticate via your browser on first use.

Windsurf

  1. Open Cascade (Cmd + L)
  2. Click Configure MCP
  3. Add a new server with the URL: <MCP_URL>

Warp

  1. Go to Settings > MCP Servers
  2. Click + Add
  3. Select Streamable HTTP
  4. Enter the following configuration:
{
  "subimage": {
    "type": "streamableHttp",
    "url": "<MCP_URL>"
  }
}

Other Clients

For any MCP-compatible client not listed above, use the following connection details:

  • URL: <MCP_URL>
  • Transport: Streamable HTTP
  • Authentication: OAuth. Your browser opens to sign you in, or a client without one shows a link and code.