StackHawk

StackHawk MCP Server enables security analytics, YAML configuration tooling, and sensitive data threat surface analysis through a modular, local or remote MCP endpoint. It lets you interact with StackHawk data sources and validation workflows from your AI tools, IDEs, or custom clients to streamline security workflows.

How to use

You connect to the StackHawk MCP Server from your MCP client (cursor, IDE, or IDE-integrated AI assistant) to run security analytics, validate YAML configurations, and map sensitive data across your apps and repos. Start the local MCP server, then point your MCP client to the appropriate stdio (local) command or to a remote HTTP endpoint if you have one. Use the client to invoke tools such as organization info, YAML validation, vulnerability searches, and data exposure analyses. The server includes a dedicated anti-hallucination layer to help ensure field names and schema compliance when you work with YAML configurations.

Key usage patterns include running the server in a Python environment, then using your MCP client to call the available tools from your prompts or code. For example, you can validate a YAML config before applying it to production, fetch organization details for a dashboard, or generate executive summaries of vulnerabilities across applications.

How to install

Prerequisites: Python 3.10 or higher and pip for Python package installation.

Install the MCP package. You can install globally or in a virtual environment.

> pip install stackhawk-mcp
# Requires Python 3.10 or higher

Or install into a virtual environment to keep dependencies isolated.

> python3 -m venv ~/.virtualenvs/mcp
> source ~/.virtualenvs/mcp/bin/activate
> (mcp) pip install stackhawk-mcp
# Requires Python 3.10 or higher

Or install via pyenv to manage the Python version explicitly.

> pyenv shell 3.10.11
> pip install stackhawk-mcp
# Requires Python 3.10 or higher

If you prefer to install locally from the repository clone, run this from the project root.

> pip install --user .

Set your API key to authorize requests.

> export STACKHAWK_API_KEY="your-api-key-here"

Additional setup and notes

To run the MCP server module and expose the tool APIs, you will execute the server entry point in your Python environment.

# Start the MCP server
python -m stackhawk_mcp.server

Configuration

All HTTP requests, when used, include a custom User-Agent header in the format StackHawk-MCP/{version}. The version is defined in the server code as STACKHAWK_MCP_VERSION. You need to provide your API key via the STACKHAWK_API_KEY environment variable.

Security notes and anti-hallucination

Leverage anti-hallucination tooling to validate field names and schema compliance before accepting user-provided YAML configurations. Regularly update the YAML schema reference to keep validations aligned with the latest StackHawk specifications.

Examples

Here are practical ways to run and use the MCP server from client tools. Use these as starting points in your own workflows.

# Start the MCP server from a virtual environment
# (adjust paths to match your setup)
/home/bobby/.virtualenvs/mcp/bin/python -m stackhawk_mcp.server

Troubleshooting and quick tips

If the server does not start, verify that Python 3.10+ is active, the STACKHAWK_API_KEY is set, and the environment has network access if you are using an HTTP endpoint. Check that the process is running and listening on the expected port if applicable.

Notes on integration with LLMs and IDEs

Connect to the MCP server from your LLM or IDE using the provided tool call interfaces. Ensure the server is reachable (local or remote) and that you pass the required arguments for each tool, such as YAML content for validation or organization identifiers for analytics.

Available tools

get_organization_info

Fetch details about a StackHawk organization for analytics and dashboards.

validate_stackhawk_config

Validate a YAML StackHawk configuration against the official schema.

validate_yaml_suggestion

Suggest YAML configuration improvements and anti-hallucination checks during editing.

get_application_vulnerabilities

Retrieve vulnerabilities for a specified application.

generate_security_dashboard

Create a summarized security dashboard for leadership visibility.

search_vulnerabilities

Search vulnerabilities across applications in your organization.

report_vulnerability_trends

Provide trend analyses of vulnerabilities over time.

report_sensitive_data

Produce reports on sensitive data exposure at org/app/repo levels.

surface_mapping

Map exposure surface points and data risk across applications and repositories.

get_schema_reference

Fetch the latest YAML/StackHawk schema reference.

create_config

Generate a new StackHawk YAML configuration from input data.

schema_cache_refresh

Refresh the locally cached schema with the latest version.

anti_hallucination_validation

Validate fields against the official schema to prevent hallucinations.