Model Context Protocol (MCP) — Vulseek
Table of Contents
- 1. Overview and Architecture
- 1.1 What is the Model Context Protocol?
- 1.2 Architecture and Design
- 1.3 Designed Exclusively for Read-Only
- 1.4 Exposed Tools
- 2. Security and Authentication
- 2.1 Principle of Least Privilege
- 2.2 Authentication Mechanism
- 2.3 Creating a Read-Only Integration Token
- 2.4 Dedicated Tokens per Client
- 3. Client Configuration
- 3.1 Configuration using OpenCode
- 3.2 Configuration using Claude Code
- 3.3 Configuration using Antigravity (Google)
- 3.4 Configuration using GitHub Copilot
- 4. Practical Prompt Examples
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:
- Navigate to Integrations → Listing.
- Click the "+" button to create the integration.
- Enter a clear, descriptive name (e.g.,
"OpenCode Assistant - Read Only"). - Select the role: "Viewer" (read-only). This role provides strictly read-only access limited to the workspace.
- Click Save.
- 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_attimestamps 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
- Open Code installed on the machine
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
- Antigravity CLI installed on the machine.
- Authenticated Google account.
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
- Github Copilot CLI installed on your machine.
- Authenticated GitHub account.
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
openstatus."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.