Adaptive Security Awareness Training MCP Server

A Model Context Protocol server that exposes the Adaptive Security Awareness Training API (v2) (REST) to AI assistants. It provides 15 tools across 5 API domains — Audit Logs, Groups, Phishing, Training, and Users — plus a generic adaptive_request escape hatch for anything not covered by a dedicated tool. The tool set is generated directly from the Adaptive OpenAPI specification, so it stays faithful to the real API surface, and the generated output is deterministic and committed.

Tools

15 tools across 5 domains (all read-only), plus the adaptive_request escape hatch — 16 total. The table below groups them by domain.

See docs/ENDPOINTS.md for the full tool ↔ method ↔ path mapping (all 15 tools).

Highlights:

• List tools (list_users, list_phishing_campaigns, …) are cursor-paginated — pass page_size and a page_after cursor; the response carries the next page_after. See Pagination & responses.
• Filter tools (get_phishing_enrollments, get_training_campaign_enrollments) narrow enrollment data by user_id / campaign_id / simulation_id.
• list_audit_logs filters the admin audit trail by start_date, end_date, and a list of actions (e.g. CREATED_TRAINING_CAMPAIGN, SCHEDULED_TRAINING_CAMPAIGN, ADDED_ADMIN).
• adaptive_request escape hatch issues a raw GET against any path for endpoints without a dedicated tool. It is GET-only by construction — it cannot mutate.

Quick start

Install

# with uv (recommended)
uv tool install adaptive-mcp

# or with pip
pip install adaptive-mcp

This installs the adaptive-mcp console script. The package is published on PyPI; a push of a v* tag publishes new releases automatically via GitHub Actions trusted publishing.

For development from source:

git clone https://github.com/Space-C0wboy/Adaptive-Security-MCP-Server
cd Adaptive-Security-MCP-Server
uv venv && uv pip install -e ".[dev]"

Getting an API token

1. In the Adaptive Admin portal, go to Settings → API Tokens.
2. Create a token and copy it — this is your ADAPTIVE_API_KEY.

Requests authenticate with the Authorization: Bearer <token> header; this server sets it for you on every request.

Configuration

Copy .env.example to .env and set:

Run

• stdio (default, for Claude Desktop/Code): adaptive-mcp (or uv run adaptive-mcp from source)
• HTTP: adaptive-mcp --transport http --port 8765

Pagination & responses

Adaptive list/filter endpoints use opaque cursor pagination via two query parameters:

Response envelope: a list response is an object with the records under a domain-named key plus the next cursor, e.g.:

{
  "users": [ { "id": "...", "email": "..." } ],
  "page_after": "eyJpZCI6..."
}

To page through everything, keep calling the same tool with page_after set to the value from the previous response until page_after comes back empty/absent.

Filter parameters on specific tools:

Editor integration

Claude Code

claude mcp add adaptive \
  --env ADAPTIVE_API_KEY=your-token-here \
  -- adaptive-mcp

Or, to run from source instead of the installed package (e.g. during development):

claude mcp add adaptive \
  --env ADAPTIVE_API_KEY=your-token-here \
  -- uv run --directory /absolute/path/to/Adaptive-Security-MCP-Server adaptive-mcp

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "adaptive": {
      "command": "adaptive-mcp",
      "env": {
        "ADAPTIVE_API_KEY": "your-token-here"
      }
    }
  }
}

If running from source instead of an installed tool, use uv with --directory:

{
  "mcpServers": {
    "adaptive": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/Adaptive-Security-MCP-Server", "adaptive-mcp"],
      "env": { "ADAPTIVE_API_KEY": "your-token-here" }
    }
  }
}

Restart Claude Desktop, then confirm adaptive appears in the tools menu.

Example prompts

• "List the first 25 users." → list_users (page_size=25).
• "Get the details for user <id>." → get_user (userId=<id>).
• "What groups do we have, and who's in the Finance group?" → list_groups → get_group_members (groupId=<id>).
• "Show our phishing campaigns and the simulations in campaign <id>." → list_phishing_campaigns → list_campaign_simulations (campaignId=<id>).
• "How did user <id> do on the phishing simulations?" → get_phishing_enrollments (user_id=<id>).
• "Which users haven't completed training campaign <id>?" → get_training_campaign_enrollments (campaign_id=<id>).
• "Show admin actions in the last week." → list_audit_logs (start_date, end_date, actions=["ADDED_ADMIN", "CREATED_TRAINING_CAMPAIGN"]).
• "Call an endpoint I don't have a dedicated tool for." → adaptive_request (path, optional params).

How tools are generated

The tool modules are generated from the Adaptive OpenAPI specification:

uv run python scripts/generate_from_openapi.py

This regenerates the modules under src/adaptive_mcp/tools/_generated/ and the catalog at docs/ENDPOINTS.md. The generated files are not hand-edited — to change a tool, edit the generator (its OVERRIDES map) and regenerate. Generation is deterministic, so re-running it produces a byte-identical, reviewable diff.

The OpenAPI spec and other Adaptive reference material live in the Source Material/ directory, which is gitignored (vendor reference material, not redistributed). CI installs from the committed _generated/ modules and does not regenerate.

Key generator behavior:

• Operations are grouped by OpenAPI tag into one module per domain.
• Only GET operations are generated (the API is read-only); path parameters are interpolated into the URL and query parameters are forwarded with their spec defaults.
• Tool names are the snake_case form of each operationId.

Development

uv run pytest        # full suite (httpx fully mocked; no live calls)
uv run ruff check .  # lint
uv run python scripts/generate_from_openapi.py  # regenerate tools + ENDPOINTS.md

CI runs ruff + pytest on Python 3.10 / 3.11 / 3.12 (see .github/workflows/ci.yml). A pushed v* tag builds and publishes to PyPI via trusted publishing (see .github/workflows/release.yml).

License

MIT

Support

This is an unofficial, internal project. For Adaptive platform or API questions, contact Adaptive Security directly. For issues with this MCP server, open an issue on the GitHub repository.