StackShield MCP Server - Connect AI Agents to Security Scanning

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents connect to external tools and data sources. Instead of manually copying data between your security dashboard and your AI assistant, MCP lets the agent interact with StackShield directly.

When you connect StackShield's MCP server to your agent, the agent automatically discovers all available capabilities: it can list your domains, trigger scans, read test results, resolve issues, and more. No extra configuration or prompt engineering needed.

Supported Agents

Any MCP-compatible agent can connect, including:

ChatGPT (as a connector)
Claude on claude.ai and Claude Desktop (as a connector)
Claude Code (Anthropic's CLI)
Cursor
VS Code (GitHub Copilot)
Codex CLI (OpenAI)
Gemini CLI (Google)
Windsurf
Any agent that supports remote MCP servers over Streamable HTTP

How Discovery Works

When an agent connects to the MCP server, it automatically discovers all available tools, resources, and prompts through the MCP protocol handshake. The agent receives:

The name and description of every tool
The parameter schema for each tool (types, required fields, allowed values)
Tool annotations (which tools are read-only, which are destructive)
Available resources and prompt templates

You don't need to describe the tools to your agent. It already knows what's available and how to use each one.

Setup

Prerequisites

A StackShield account on any plan, including the free trial
Nothing else for most clients: they send you to StackShield to sign in. Scripts and clients that cannot open a browser use a team API key from Settings > API Keys

Server URL

The MCP server endpoint is:

https://stackshield.io/mcp

It speaks Streamable HTTP. Discovery documents live at https://stackshield.io/.well-known/oauth-protected-resource/mcp and https://stackshield.io/.well-known/oauth-authorization-server.

Two ways to authenticate

Sign in with StackShield (OAuth). ChatGPT, Claude, Claude Code, Cursor, VS Code, Codex and Gemini CLI all connect by sending you to StackShield to sign in and approve access. There is no key to copy. The connection is tied to your user account and works on whichever team you currently have selected in the dashboard. Revoke it from Settings > API Keys > Connected Assistants or from the client's own settings.

Team API key. Scripts and clients without a browser pass a key as Authorization: Bearer YOUR_API_KEY, or as an api_key query parameter for clients that cannot set headers. It is the same key you use for the REST API and is scoped to the team that owns it.

ChatGPT

Once StackShield is listed in the ChatGPT plugins directory, find it under Settings > Apps and choose Connect. Until then, or on a workspace that allows custom connectors, open Settings > Connectors > Create, give the connector a name and paste the server URL above. Leave authentication on OAuth. ChatGPT registers itself with StackShield, sends you to the sign-in page, and asks you to approve access to your current team. Enable it in a chat and ask ChatGPT about your domains.

Claude (claude.ai and Claude Desktop)

Once StackShield is in the Claude connectors directory, open Settings > Connectors, find StackShield and choose Connect. To add it by hand, choose Add custom connector and paste the server URL above. Leave the client ID and secret empty; Claude registers itself. Click Connect, sign in to StackShield if prompted and approve access. The connector is then available in every conversation, and in Claude Desktop.

Claude Code

Add the server, then sign in:

claude mcp add --transport http stackshield https://stackshield.io/mcp
claude mcp login stackshield

Or add it to your project's .mcp.json and run /mcp inside Claude Code to sign in:

{
  "mcpServers": {
    "stackshield": {
      "type": "http",
      "url": "https://stackshield.io/mcp"
    }
  }
}

To use a team API key instead, pass --header "Authorization: Bearer YOUR_API_KEY" to claude mcp add, or add a headers object to the JSON entry.

Cursor

Add StackShield to Cursor

The button opens Cursor and offers to add the server; approve it, then click Sign in next to the server in Settings > MCP. To add it by hand, put this in .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "stackshield": {
      "url": "https://stackshield.io/mcp"
    }
  }
}

For a team API key add "headers": { "Authorization": "Bearer YOUR_API_KEY" } to the entry.

VS Code

Add StackShield to VS Code

The button opens VS Code and asks you to confirm the server. VS Code then prompts you to sign in the first time Copilot uses it. To add it by hand, put this in .vscode/mcp.json, or run code --add-mcp '{"name":"stackshield","type":"http","url":"https://stackshield.io/mcp"}':

{
  "servers": {
    "stackshield": {
      "type": "http",
      "url": "https://stackshield.io/mcp"
    }
  }
}

Codex CLI

codex mcp add stackshield --url https://stackshield.io/mcp
codex mcp login stackshield

Or add it to ~/.codex/config.toml:

[mcp_servers.stackshield]
url = "https://stackshield.io/mcp"

Gemini CLI

gemini mcp add --transport http -s user stackshield https://stackshield.io/mcp

Or add it to ~/.gemini/settings.json. Gemini CLI discovers the sign-in flow from the first 401 response:

{
  "mcpServers": {
    "stackshield": {
      "httpUrl": "https://stackshield.io/mcp"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json and choose Sign in on the server in the MCP panel, or add a headers object with a team API key:

{
  "mcpServers": {
    "stackshield": {
      "serverUrl": "https://stackshield.io/mcp"
    }
  }
}

Claude Desktop (API key)

Claude Desktop normally uses the connector above. If you would rather use a team API key, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "stackshield": {
      "url": "https://stackshield.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Config file location:

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

Keep your API key secret

If you use a key rather than signing in, do not commit MCP config files containing it to version control. Add .mcp.json, .cursor/mcp.json, and .vscode/mcp.json to your .gitignore.

Available Tools

The MCP server exposes 16 tools organized into five groups. Your agent discovers these automatically on connection. Tools annotated as read-only only retrieve data. Destructive tools may prompt for confirmation in your agent.

Checks (Monitored Domains)

Tool	Description	Type
list_checks	List all monitored domains with optional filtering and sorting	Read
get_check	Get detailed info about a domain including schedule and latest scan	Read
create_check	Add a new domain to monitor	Write
update_check	Update check settings (schedule, tests, active status)	Write
delete_check	Remove a monitored domain	Destructive

Scans

Tool	Description	Type
list_scans	List scans with filters by check, status, and critical issues	Read
get_scan	Get scan status and all individual test results	Read
trigger_scan	Start a new security scan for a domain	Write

Scan Tests

Tool	Description	Type
get_scan_test	Get detailed test result with findings, remediation steps, and technical details	Read

Issues

Tool	Description	Type
list_issues	List issues with filters (severity, status, domain, test type, search)	Read
get_issue	Get issue details with related scans	Read
resolve_issue	Mark an issue as resolved with optional notes	Write
unresolve_issue	Re-open a resolved issue	Write
bulk_resolve_issues	Resolve or unresolve multiple issues at once	Write
export_issues_csv	Export all issues as CSV text	Read

Dashboard

Tool	Description	Type
get_dashboard_stats	Security posture overview: domains, active scans, priority issues, domains at risk	Read

Resources

MCP resources are read-only data your agent can pull at any time. They're useful for giving the agent background context without explicitly calling a tool.

URI	Description
stackshield://checks	All monitored domains with their active status and latest scan results
stackshield://issues/critical	All unresolved critical and high severity security issues
stackshield://stats	Dashboard statistics: total domains, active scans, priority issues, domains at risk

Prompts

MCP prompts are pre-built templates your agent can use to perform common multi-step workflows. They guide the agent through a sequence of tool calls to produce a useful result.

security_review

Reviews the security posture of a domain and provides actionable recommendations.

Argument	Required	Description
domain	Yes	The domain to review (e.g. "example.com")

The agent will look up the check, list all unresolved issues, and produce a prioritized remediation plan grouped by severity.

scan_report

Generates a comprehensive report of the latest security scan for a domain.

Argument	Required	Description
domain	Yes	The domain to report on (e.g. "example.com")

The agent will retrieve the latest scan, inspect each failed test, and produce a structured report with executive summary, detailed findings, and next steps.

Example Conversations

Here are examples of what you can ask your agent once StackShield is connected.

Check your security posture

You:

"What's the security status of my domains?"

The agent will:

Call get_dashboard_stats to get the overview
Call list_issues with status=unresolved and severity=critical
Summarize your posture and highlight anything urgent

Scan and review a domain

You:

"Run a security scan on example.com and tell me what failed"

The agent will:

Call list_checks to find the check for example.com
Call trigger_scan to start the scan
Poll get_scan until the scan completes
Call get_scan_test for each failed test to get findings and fixes
Present a summary of what failed and how to fix each issue

Resolve issues in bulk

You:

"I've fixed all the SSL issues, mark them as resolved"

The agent will:

Call list_issues with test_type=ssl_certificate and status=unresolved
Call bulk_resolve_issues with all the matching issue IDs
Confirm how many issues were resolved

Add a new domain

You:

"Add staging.example.com with daily scans and all tests enabled"

The agent will:

Call create_check with the domain, DAILY frequency, and all tests set to true
Confirm the check was created and show the schedule

Authentication & Security

Every connection is authenticated. Either an OAuth token issued after you sign in and approve access, or a team API key. Unauthenticated requests get a 401 with the OAuth discovery address, which is how connectors find the sign-in flow.
OAuth 2.1 with PKCE. Connectors register themselves (dynamic client registration) and request a single scope, mcp:use. Access tokens expire after an hour and are refreshed silently for up to 90 days.
Team scoped. An API key sees the team that owns it. An OAuth connection sees the team you currently have selected in the dashboard. Neither can reach another team's data.
No account changes. The MCP server cannot change billing, invite or remove members, or manage API keys.
Every plan. MCP works on every plan and during the trial, reads and writes alike. Plan limits still apply inside the tools: create_check respects your domain limit and trigger_scan your daily manual scan limit. A team with no plan or an expired trial receives a 403 error.
Same key as the REST API. Your existing API key works for both.
Confirmation for irreversible actions. delete_check and bulk_resolve_issues refuse to run unless the agent passes confirm: true, which it should only do after checking with you.

Troubleshooting

Agent can't connect

Verify your API key is correct and active in Team Settings
Connecting through OAuth: make sure you are signed in to StackShield in the same browser, and that the team selected in the dashboard is the one you want the assistant to see
Check that your team has an active plan or trial
Ensure the URL includes the full path: https://stackshield.io/mcp
Test the connection with the MCP Inspector: npx @modelcontextprotocol/inspector "https://stackshield.io/mcp" --header "Authorization: Bearer YOUR_KEY"

Tools not appearing

Restart your agent after adding the MCP configuration
Check the agent's MCP logs for connection errors
In Claude Desktop: Settings > Developer > MCP Servers to see connection status

"Does not belong to your team" errors

All data is team-scoped. If you're getting ownership errors, make sure the check, scan, or issue ID belongs to the team associated with your API key, or to the team currently selected in the dashboard for an OAuth connection.