MCP Server — Quick Start Guide

This guide helps you connect an MCP-compatible AI assistant, such as Cursor, Claude, GitHub Copilot, or VS Code, to the NetSPI Platform MCP Server.

The MCP Server lets your AI assistant securely query NetSPI platform data, retrieve finding and engagement details, export data, and generate reports using your existing NetSPI platform permissions.

What You Need

Before you begin, make sure you have:

A NetSPI platform API token
Docker installed on your machine
Network access to the NetSPI platform
The NetSPI platform base URL for your environment
The public MCP Server image link: https://gallery.ecr.aws/s2u9k8v8/netspi/platform-mcp
The Docker image URI: public.ecr.aws/s2u9k8v8/netspi/platform-mcp

No AWS account, AWS CLI, or AWS Elastic Container Registry login is required.

VM Requirements for the hosting container

Users	vCPU	RAM	Disk
10 users	2 vCPU	4 GiB RAM	10–20 GiB disk
20+ users	3–4 vCPU	8 GiB RAM	20–40 GiB disk
40+ users (recommended multi-replica)	4 vCPU+	8 GiB RAM	20–40 GiB disk

1. Create a NetSPI Platform API Token

Log in to the NetSPI platform.
Go to Upper Right Profile Image > My Profile > API.
Generate a new API token.
Copy the token and store it securely.

The token is shown only once. Platform API tokens may expire, so generate a new one if your current token no longer works.

2. Pull the MCP Server Image

The MCP Server image is available through the Amazon ECR Public Gallery:

https://gallery.ecr.aws/s2u9k8v8/netspi/platform-mcp

Use Docker to pull the image directly from the public image URI:

docker pull public.ecr.aws/s2u9k8v8/netspi/platform-mcp:beta

If NetSPI provides a specific version tag, replace latest with that tag:

docker pull public.ecr.aws/s2u9k8v8/netspi/platform-mcp:<version>

3. Confirm the Image Is Available Locally

On Linux, after the pull completes, confirm that Docker can see the image:

docker images | grep platform-mcp

On Windows, after the pull completes, confirm that Docker can see the image:

docker images | findstr platform-mcp

You should see an image similar to:

public.ecr.aws/s2u9k8v8/netspi/platform-mcp   beta   ...

Use the image tag shown by Docker in the next step.

4. Start the MCP Server

Run the MCP Server container:

docker run -d \
  --name netspi-mcp \
  -p 127.0.0.1:4490:4490 \
  -e PLATFORM_API_BASE_URL=https://platform.netspi.ai \
  public.ecr.aws/s2u9k8v8/netspi/platform-mcp:beta

Run the MCP Server container in Windows:

docker run \
  --name netspi-mcp \
  -p 127.0.0.1:4490:4490 \
  -e PLATFORM_API_BASE_URL=https://platform.netspi.ai \
  -d public.ecr.aws/s2u9k8v8/netspi/platform-mcp:beta

Replace:

latest with the specific image tag if NetSPI provided one

The server will listen locally at:

http://localhost:4490/mcp/sse

Binding to 127.0.0.1 restricts access to local AI clients on your machine.

5. Verify the Server Is Running

Check the MCP Server health endpoint:

curl http://localhost:4490/health

Or:

docker ps

A healthy response should look similar to:

{
  "status": "UP",
  "platform": {
    "status": "UP"
  }
}

If the server is running but the platform status is DOWN, verify that:

PLATFORM_API_BASE_URL is correct
Your machine can reach the NetSPI platform over HTTPS
Your firewall, VPN, or proxy is not blocking outbound access

6. Configure Your AI Assistant

Use the MCP Server URL and your NetSPI platform API token in your AI assistant configuration.

Cursor

Add this to .cursor/mcp.json for a project-level setup, or ~/.cursor/mcp.json for a global setup:

{
  "mcpServers": {
    "netspi-platform": {
      "url": "http://localhost:4490/mcp/sse",
      "headers": {
        "x-token": "<your-platform-api-token>",
        "x-app-name": "netspi-platform"
      }
    }
  }
}

Claude Code

Run:

claude mcp add --transport sse netspi-platform http://localhost:4490/mcp/sse \
  --header "x-token: <your-platform-api-token>" \
  --header "x-app-name: netspi-platform"

Claude Desktop

Claude Desktop can connect to the local MCP Server using mcp-remote.

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "netspi-platform": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:4490/mcp/sse",
        "--header",
        "x-token: <your-platform-api-token>",
        "--header",
        "x-app-name: netspi-platform",
        "--transport",
        "sse-only"
      ]
    }
  }
}

Claude Desktop requires Node.js 24 or later for this setup.

GitHub Copilot or VS Code

Add this to your VS Code settings.json:

{
  "github.copilot.chat.mcpServers": {
    "netspi-platform": {
      "url": "http://localhost:4490/mcp/sse",
      "headers": {
        "x-token": "<your-platform-api-token>",
        "x-app-name": "netspi-platform"
      }
    }
  }
}

Other MCP-Compatible Clients

Use these settings:

Setting	Value
Server URL	`http://localhost:4490/mcp/sse`
Auth header name	`x-token`
Auth header value	Your NetSPI platform API token
App header name	`x-app-name`
App header value	`netspi-platform`

7. Try Example Prompts

Once connected, try prompts like:

List all critical open findings for client 42.
Show me engagements that started in the last 30 days.
Get the full detail for finding ID 1234.
Export all high and critical findings for client 10 as JSON.
Generate the PDF report for report ID 99.

Your AI assistant can only access data that your NetSPI platform account is authorized to see.

Available MCP Tools

The MCP Server currently supports these platform actions:

Tool	Purpose
`list_query_models`	Lists available platform data models
`get_model_schema`	Shows fields and types for a model
`query_data`	Queries platform data with filters, columns, sorting, and pagination
`get_finding_detail`	Retrieves full detail for a finding
`get_engagement_detail`	Retrieves full detail for an engagement or project
`generate_report`	Generates a PDF report for a report ID
`export_data_table`	Exports query results as CSV or JSON

Updating the MCP Server Image

When NetSPI provides a new version tag, pull the updated image:

docker pull public.ecr.aws/s2u9k8v8/netspi/platform-mcp:<new-version>

If NetSPI tells you to use the latest published image, pull latest again:

docker pull public.ecr.aws/s2u9k8v8/netspi/platform-mcp:latest

Stop and remove the old container:

docker stop netspi-mcp && docker rm netspi-mcp

Start the new version:

docker run -d \
  --name netspi-mcp \
  -p 127.0.0.1:4490:4490 \
  -e PLATFORM_API_BASE_URL=https://platform.netspi.ai \
  public.ecr.aws/s2u9k8v8/netspi/platform-mcp:<new-version>

Windows:

docker run \
  --name netspi-mcp \
  -p 127.0.0.1:4490:4490 \
  -e PLATFORM_API_BASE_URL=https://platform.netspi.ai \
  -d public.ecr.aws/s2u9k8v8/netspi/platform-mcp:beta

Replace <new-version> with the tag NetSPI provided, or use latest if that is the version you pulled.

Check the running version:

curl -s http://localhost:4490/health
docker ps

Troubleshooting

Issue	Likely Cause	What to Do
AI assistant shows no tools	MCP Server is not running or failed to start	Run `docker logs netspi-mcp` and check `curl http://localhost:4490/health`
Health check shows platform DOWN	The MCP Server cannot reach the NetSPI platform	Verify `PLATFORM_API_BASE_URL`, VPN, proxy, and network access
Tool calls return 401 Unauthorized or say no API token	Missing or invalid `x-token` header	Check your AI client config and confirm the token is current
Tool calls return 403 Forbidden	Your token is valid, but your account lacks access	Confirm you have access to the requested client or tenant
Tool calls return 429 Too Many Requests	Rate limit exceeded	Wait and retry; reduce repeated or automated requests
Docker cannot pull the image	Wrong image URI, missing tag, or local Docker auth cache issue	Use `public.ecr.aws/s2u9k8v8/netspi/platform-mcp:<tag>` and retry. If Docker mentions an expired public ECR token, run `docker logout public.ecr.aws` and pull again
Docker says the port is already in use	Another process is using port 4490	Stop the other process or map a different local port
Tool calls time out	Query is too large or slow	Ask for fewer results or include a limit in your prompt

Security Notes

The MCP Server does not store platform data.
The MCP Server does not store your API token.
Your API token is passed through to the NetSPI platform on each request.
The API token has the same permissions as the user the token is associated to.
Platform permissions and tenant access are enforced by the NetSPI platform.
Keep your API token private and do not commit it to source control.
Run the MCP Server bound to 127.0.0.1 unless you intentionally need remote access.

Quick Reference

Item	Value
Public image gallery	https://gallery.ecr.aws/s2u9k8v8/netspi/platform-mcp
Docker image URI	`public.ecr.aws/s2u9k8v8/netspi/platform-mcp`
Local MCP Server URL	`http://localhost:4490/mcp/sse`
Health check URL	`http://localhost:4490/health`
Required environment variable	`PLATFORM_API_BASE_URL`
Default port	4490
Required auth header	`x-token`
Recommended app header	`x-app-name: netspi-platform`