# 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

1. Log in to the NetSPI platform.
2. Go to **Upper Right Profile Image > My Profile > API**.
3. Generate a new API token.
4. 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:

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

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

```bash
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:

```bash
docker images | grep platform-mcp
```

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

```powershell
docker images | findstr platform-mcp
```

You should see an image similar to:

```text
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:

```bash
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:

```powershell
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:

```bash
curl http://localhost:4490/health
```

Or:

```bash
docker ps
```

A healthy response should look similar to:

```json
{
  "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:

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

### Claude Code

Run:

```bash
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`:

```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`:

```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:

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

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

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

Stop and remove the old container:

```bash
docker stop netspi-mcp && docker rm netspi-mcp
```

Start the new version:

```bash
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:

```powershell
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:

```bash
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` |