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.

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 tokens regularly from the API Keys page
• Store tokens securely (e.g., environment variables, secret managers)
• Never commit tokens to version control

Available Tools

Once connected, your AI assistant has access to the following tools:

Security Findings & Compliance

Vulnerability Management

Attack Path Discovery

Issues

Cloud Inventory

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

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>"
    }
  }
}

3. 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 will open to authenticate)