Skip to content

Model Context Protocol (MCP) — Vulseek


Table of Contents


1. Overview and Architecture

1.1 What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that allows artificial intelligence assistants and agents to securely interact with tools and data sources. Vulseek implements MCP to enable AI-powered tools — such as OpenCode, Claude Code, and others — to query your vulnerability, asset, and finding data in real time.

With Vulseek MCP you can:

  • Ask questions like "What are the most critical vulnerabilities in my environment?"
  • Automate security queries using AI assistants.
  • Integrate Vulseek data into your development workflow without leaving your editor or terminal.

1.2 Architecture and Design

Vulseek MCP is an embedded MCP server that runs directly inside the Vulseek API platform. There is no separate service to deploy or maintain. The architecture follows these principles:

Property Value
Protocol Model Context Protocol (MCP)
Server Embedded inside the Vulseek application
Mount point /mcp
Transport Stateless HTTP
Design Read-only — only GET endpoints are exposed

The server is designed using a stateless HTTP transport, meaning each request is self-contained and does not rely on persistent connections. This makes it simple, reliable, and compatible with a wide range of AI clients.

1.3 Designed Exclusively for Read-Only

Security is a foundational design principle. Vulseek MCP is strictly read-only. Only GET endpoints are exposed through the protocol. All data-modifying methods (POST, PUT, PATCH, DELETE) are explicitly excluded.

This ensures that:

  • An AI assistant can query your data but not modify it.
  • Accidental or malicious modification of findings, assets, or vulnerabilities is impossible via MCP.
  • Configuring it with a read-only token guarantees that the AI assistant or agent cannot make unintended modifications to your environment outside of MCP.

1.4 Exposed Tools

Vulseek MCP exposes more than 30 read tools for your workspace, allowing you to perform various queries on the following information:

  • Assets
  • Asset properties
  • Findings
  • Finding properties
  • Vulnerabilities
  • Vulnerability properties

Recommendation: Each tool includes filters. Try to specify as much detail as possible in your query prompts so the AI assistant uses them and avoids overly verbose responses.

2. Security and Authentication

⚠️ IMPORTANT: Security is the highest priority when integrating AI assistants with security data. Read this section carefully before configuring any client.

2.1 Principle of Least Privilege

When connecting an AI assistant or agent to Vulseek, always follow the Principle of Least Privilege:

  • Never use your personal password or session token with write permissions in AI assistants.
  • Never use administrator credentials for API access.
  • Never share or embed secrets directly in configuration files that could be committed to version control.
  • Always create a dedicated integration token with the minimum required permissions (read-only).

2.2 Authentication Mechanism

Vulseek MCP authenticates requests using the X-API-Key HTTP header. Each request to the MCP server must include this header with a valid integration token.

X-API-Key: <integration_id>@<secret>

Remote URL

  • If your environment is in production, use:
https://api.vulseek.io/mcp
  • If your environment is in staging, use:
https://stage.api.vulseek.io/mcp

2.3 Creating a Read-Only Integration Token

To create an access token for AI assistants, follow these steps in the Vulseek web interface:

  1. Navigate to Integrations → Listing.
  2. Click the "+" button to create the integration.
  3. Enter a clear, descriptive name (e.g., "OpenCode Assistant - Read Only").
  4. Select the role: "Viewer" (read-only). This role provides strictly read-only access limited to the workspace.
  5. Click Save.
  6. Copy and store the token securely immediately. The token is shown only once, in the format <integration_id>@<secret>. If you lose it, you must create a new integration.

2.5 Dedicated Tokens per Client

Always generate a unique integration token for each AI tool or assistant you use. For example:

Assistant / Tool Token Name
OpenCode Assistant "OpenCode Assistant - Read Only"
Claude Code Security Agent "Claude Code Security Agent"
Custom automation script "Automation - Weekly Report"

Benefits of dedicated tokens:

  • Granular auditing: The last_login_at timestamps for each token are recorded independently.
  • Isolated access: Revoking a token does not affect other integrations.
  • Simple revocation: If a specific assistant is deprecated or compromised, you only need to delete its token.

3. Client Configuration

3.1 Configuration using OpenCode

Requirements

Step 1: Create the MCP

Create or edit ~/.opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vulseek": {
      "type": "remote",
      "url": "https://api.vulseek.io/mcp",
      "enabled": true,
      "headers": {
        "X-API-Key": "<integration_id>@<secret>"
      }
    }
  }
}

Step 2: Verify that the MCP server is properly configured

Run the following command in your terminal:

opencode mcp ls

The command output should look similar to:

●  ✓ vulseek connected https://api.vulseek.io/mcp

3.2 Configuration using Claude Code

Requirements

  • Claude Code installed on the machine.
  • Active Anthropic subscription.

Step 1: Set the API Key via environment variable

Create or edit the ~/.claude/settings.json file with the following content:

{
  "env": {
    "VULSEEK_API_KEY": "<integration_id>@<secret>"
  }
}

Step 2: Create the MCP

claude mcp add --scope user --transport http vulseek \
  https://api.vulseek.io/mcp \
  --header "X-API-Key: ${VULSEEK_API_KEY}"

Step 3: Verify that the MCP server is properly configured

Run the following command in your terminal:

claude mcp list

The command output should look similar to:

vulseek: https://api.vulseek.io/mcp (HTTP) - ✔ Connected

3.3 Configuration using Antigravity (Google)

Requirements

Step 1: Create the MCP

Create or edit ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "vulseek": {
      "serverUrl": "https://api.vulseek.io/mcp/",
      "headers": {
        "X-API-Key": "<integration_id>@<secret>"
      },
      "timeoutSeconds": 600
    }
  }
}

Step 2: Verify that the MCP server is properly configured

Run the following command in your terminal:

agy mcp list

The command output should look similar to:

●  vulseek  http  enabled  https://api.vulseek.io/mcp/

3.4 Configuration using GitHub Copilot

Requirements

Step 1: Create the MCP

Create or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "vulseek": {
      "type": "http",
      "url": "https://api.vulseek.io/mcp",
      "headers": {
        "X-API-Key": "<integration_id>@<secret>"
      },
      "tools": ["*"]
    }
  }
}

Step 2: Verify that the MCP server is properly configured

Run the following command in your terminal:

copilot mcp list

The command output should be similar to the following:

User servers:
  vulseek (http)

4 Practical Prompt Examples

Once your client is configured, you can ask questions like these:

"Show me all critical vulnerabilities in my Vulseek environment."

The assistant will return a list of vulnerabilities with critical severity.

"How many open findings do we have loaded in Vulseek corresponding to public IPs?"

The assistant will return a count (sometimes with a summary) of findings associated with public IP addresses filtered by open status.

"Give me a summary of our security posture by severity."

The assistant should display a summary of findings by severity level.

"I need to resolve the findings detected in Vulseek and I don't have much time. Where should I start? What do you recommend?"

This query may trigger calls to multiple MCP tools so the assistant can retrieve detailed information on assets, vulnerabilities, and findings. It should provide guidance to get started with the most relevant security issues.

"Generate a report based on the critical and high severity findings identified in my Vulseek environment"

This query may trigger calls to multiple MCP tools so the assistant can retrieve detailed information on assets, vulnerabilities, and findings. It should build a general report (usually in Markdown format), but the tone, content, and format can be adjusted by specifying more details in the prompt.