MCP Integration

MCP lets an AI application connect to external context and tools through a standard protocol. For security remediation, use it to give an agent the evidence it needs to fix one finding: the recipe, advisory data, scanner output, repository context, and review rules.

Last reviewed against the public MCP documentation and this repository’s mcp_server.py implementation on June 14, 2026.

MCP in one minute

The Model Context Protocol is an open standard for connecting AI applications to external systems. The current public specification page identifies version 2025-11-25 as the latest stable spec.

The main roles are:

MCP servers can expose:

MCP uses JSON-RPC. The standard transports are stdio and Streamable HTTP. Use Streamable HTTP for hosted or browser-reachable servers. Use stdio when the client starts a local subprocess.

Recommended context stack

Start with three layers. Add more only when the finding requires it.

An agent does not need every connector for every task. A dependency update may need only the recipe, package metadata, lockfile, and CI. A SAST remediation may need the SARIF alert, affected source file, related tests, and secure coding rule.

Read-only context

Read-only context means the agent can retrieve evidence, but the context layer does not give it mutation authority. The agent may search recipes, fetch a scanner finding, read an advisory, inspect a repository file, or collect CI status. It should not create tickets, push branches, edit secrets, rotate keys, deploy, dismiss alerts, or write back to source systems through the same connector.

That split matters because context gathering is high-volume and low-risk, while mutation is where authorization mistakes become durable. Keep the default MCP profile read-only and route write-capable tools through a separate approval path.

For a remediation run, a read-only context packet usually includes:

• the selected recipe and its stop conditions;
• the specific finding, alert, CVE, GHSA, package, rule, or source/sink pair;
• affected source files, manifests, lockfiles, SBOMs, SARIF, and CI logs;
• relevant ownership and review policy, such as CODEOWNERS or branch protection;
• generated evidence requirements that the PR must satisfy.

If a workflow truly needs mutation, split the flow: use read-only MCP to gather context first, then ask for a narrower write grant tied to one action, one repository, one branch, one ticket, or one output route. The review step should be able to see which grant was used and why.

Security Recipes MCP server

This repository includes an optional FastMCP server in mcp_server.py. It is a read-first knowledge server for security-recipes.ai.

It exposes MCP tools that let compatible clients:

The exact tool list is available through your MCP client’s tools/list view. This repo currently defines 66 recipes_* tools.

What it is not

The Security Recipes MCP server is not a scanner, ticket writer, deployment system, or general-purpose command runner. Its default job is to retrieve recipes and generated evidence. If you add upstream MCP servers, keep that bridge read-only unless a separate review approves mutation.

Which endpoint should I use?

Opening /mcp in a normal browser can show an MCP or HTTP method error. That is expected. MCP clients connect by sending JSON-RPC messages over the selected transport.

Configure this Security Recipes MCP server

Use the values below for the page you are viewing now. They update from the browser’s current host, so a local Docker port such as 127.0.0.1:18080, a plain localhost run, and the hosted security-recipes.ai site all produce the right client URL and public metadata.

{}

RECIPES_MCP_SOURCE_INDEX_URL=...

source_index_url = "..."

docker compose ps

For Docker Compose, keep RECIPES_MCP_SOURCE_INDEX_URL on the internal http://security-recipes/api/recipes.json feed. That lets the MCP container read the exact recipes built from this checkout, even before a public domain or TLS certificate is ready. For a standalone MCP server, point source_index_url at the public recipe feed shown above.

Quick local setup

Run the site and MCP server together:

docker compose up -d --build

Then connect an MCP client to:

http://localhost/mcp

For clients that accept JSON configuration, adapt this shape to the client’s own config format:

{
  "mcpServers": {
    "security-recipes": {
      "transport": "streamable-http",
      "url": "http://localhost/mcp"
    }
  }
}

If you want to run only the MCP image:

docker build -f Dockerfile.mcp-server -t security-recipes-mcp .
docker run --rm -p 8123:80 security-recipes-mcp

Then use:

http://localhost:8123/mcp

If a client only supports local stdio servers, run the Python server with RECIPES_MCP_TRANSPORT=stdio and do not publish an HTTP port.

First tool calls to try

After the client connects, start with low-risk read calls:

1. Call recipes_server_info to confirm the source index, cache TTL, and upstream server count.
2. Call recipes_search with a short finding description, for example log4j dependency update or stored xss sanitizer bypass.
3. Call recipes_match_finding with a CVE, package, ecosystem, rule ID, or keywords.
4. Call recipes_get with a returned slug or path to retrieve the full recipe record.
5. Call recipes_quality_report to inspect quality tiers and improvement gaps before promoting recipes into automated workflows.

Use facets and quality thresholds when the agent knows the job shape:

{
  "query": "SSDF repository evidence",
  "facets": ["compliance", "audit"],
  "min_quality": 70,
  "limit": 3
}

Facet filters align recipe selection with the intended output: remediation for patch work, risk for exploitability and impact, audit for evidence mapping, compliance for standards readiness, and code-hygiene for source cleanup or hardening. min_quality lets agents prefer recipes with stronger inputs, output contracts, verification, guardrails, and related context.

To maintain the recipe library itself, call:

{
  "facet": "compliance",
  "limit": 10
}

against recipes_quality_report. The response lists recipes below world-class readiness and names the missing quality signals to add next.

If those work, add evidence-pack tools only when the workflow needs them.

Custom configuration

Copy the template before changing server behavior:

Copy-Item mcp-server.toml.example mcp-server.toml

Mount it into the container:

docker run --rm -p 8123:80 `
  -v "${PWD}/mcp-server.toml:/app/mcp-server.toml:ro" `
  security-recipes-mcp

Use mcp-server.toml to change:

• source_index_url: the generated /api/recipes.json agent feed to read. The legacy /recipes-index.json array is still accepted.
• allowed_source_hosts: the host allow-list for that index.
• generated evidence-pack file paths.
• cache TTL, request timeout, and result limits.
• optional upstream MCP servers.

Keep credentials out of the TOML file. Put secrets in environment variables.

Optional upstream MCP context

No upstream MCP servers are configured by default. That keeps the public/site deployment from holding customer credentials or spending third-party tokens.

For a business deployment, add one [[upstream_mcp_servers]] entry per approved HTTP or Streamable HTTP endpoint:

[[upstream_mcp_servers]]
id = "github"
label = "GitHub MCP Server"
description = "Repository, issue, PR, Actions, and code-security context."
url = "https://YOUR-GITHUB-MCP-ENDPOINT/mcp"
auth_token_env = "GITHUB_TOKEN"
allowed_tools = ["search_repositories", "get_issue", "get_pull_request"]
context_tool = "search_repositories"
context_query_argument = "query"
max_response_chars = 12000

Then pass the token at runtime:

docker run --rm -p 8123:80 `
  -e GITHUB_TOKEN="$env:GITHUB_TOKEN" `
  -v "${PWD}/mcp-server.toml:/app/mcp-server.toml:ro" `
  security-recipes-mcp

Only HTTP or Streamable HTTP upstreams are called directly. If an upstream connector is stdio-only, run it behind a reviewed internal gateway before attaching it to this server.

For production, prefer explicit allowed_tools. Do not rely on tool-name heuristics for connectors that can access private code, cloud resources, customer data, tickets, deployments, secrets, or terminals.

Public and product context sources

Not every useful source needs to be an MCP server. Use the simplest safe source that provides the evidence.

Do not install random MCP servers because they mention security. Review source, package provenance, token scopes, network access, tool descriptions, update cadence, and whether the connector can write or execute commands.

Recipe API and MCP support

The site exposes recipes through static JSON feeds and the optional read-only MCP server. Use those surfaces to let approved agents search, retrieve, and match recipes without adding a site-hosted chatbot.

Local stdio MCP servers should run in the agent host’s native MCP client. Wrap only reviewed connectors behind an approved HTTP gateway when browser or hosted clients need access.

Connector policy

Before adding any MCP server to a remediation workflow, answer these questions:

Per-agent setup pattern

Every client config looks different, but the safe shape is the same:

1. Add the recipe source or Security Recipes MCP endpoint.
2. Add only the MCP servers needed for the finding class.
3. Grant read-only scopes first.
4. Put stop conditions in the agent’s native rules file.
5. Test with one low-risk finding before using the connector on a backlog.

Example task text:

Use the matching security-recipes.ai recipe.
Read advisory and repository context from approved read-only MCP connectors.
Do not use write-capable MCP tools.
Make one PR or stop with a triage note.

Troubleshooting

When not to use MCP

Skip MCP when a local file or task attachment is enough. A scanner alert copied into an issue, a vendored recipe file, and the repository’s test command may be better for a small dependency bump.

Use MCP when the agent needs fresh structured context: advisory metadata, code scanning results, SBOM evidence, CI status, ownership data, or a large recipe catalog that would be awkward to paste into every task.

See also

• Integrate an AI Agent
• Agent Setup
• Recipe Browser
• Security Remediation
• Local MCP runbook