> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md).

# MCP Server

Bring Heeler's live security context into your AI coding agent over MCP, so it reasons about real risk — reachability, exposure, and findings — as it writes.

The Heeler **MCP server** puts your security platform inside the coding agent. Over the Model Context Protocol, an agent can pull **live, read-only context from Heeler** — SAST findings, dependency vulnerabilities, endpoint exposure, runtime/deployment risk, package intelligence, guardrail status, and SLO pressure — and reason about real risk *as it writes the code*, before a commit ever happens.

{% hint style="info" %}
**Who this is for:** developers working in an MCP-compatible agent (Claude Code, Claude, ChatGPT connectors, Cursor, Codex CLI, VS Code, Notion Custom Agents, and other OpenCode-style clients). **This page is about what the server does and how to use it.** To connect a client — endpoints, OAuth, and per-client config — see [Set Up Developer Tooling → Connect the MCP Server](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/mcp.md). For the exact tool and prompt names, see the [MCP Tools and Prompts](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md) reference.
{% endhint %}

{% hint style="info" %}
**Not in an editor?** The same live Heeler context and assistant is also available in **Slack** — ask `@Heeler` in a channel, no MCP client required. See [Heeler in Slack](/mrecEO40m5D6bt7Pq5pE/operate/heeler-in-slack.md).
{% endhint %}

## What the server gives your agent

Rather than guessing, the agent asks Heeler and gets your real, correlated data. There are more than **30 tools**; they fall into a few groups:

| Context                         | What the agent can pull                                                                                                                                                                |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Findings & triage**           | Search findings by scope, status, and priority; drill into one finding; counts and trends; the overdue/due-soon SLO queue.                                                             |
| **Code security (SAST)**        | Findings for a repository or the specific file being edited — weakness, severity, and the data-flow behind it.                                                                         |
| **Dependencies (SCA)**          | Vulnerabilities and remediation options for the project's packages, prioritized by real risk.                                                                                          |
| **Vulnerabilities (CVE)**       | Where a CVE exists across your repos, services, and teams, and its blast radius.                                                                                                       |
| **Package intelligence**        | Investigate a specific package — where it's used, its open findings, and its safest version.                                                                                           |
| **Endpoints & exposure**        | The API attack surface and which routes are authenticated or internet-accessible.                                                                                                      |
| **Runtime & deployment**        | What's actually deployed and reachable, so the agent triages by real exposure — not just severity.                                                                                     |
| **Service & portfolio posture** | A service risk brief, or a leadership snapshot of open risk and hot spots.                                                                                                             |
| **Remediation planning**        | Fix-many groups — the single upgrades that close the most findings.                                                                                                                    |
| **Guardrails & SLOs**           | Guardrail status for a PR or finding, and SLO pressure for the code in hand.                                                                                                           |
| **Agent-file governance**       | The AI agent instruction files, skills, and subagents Heeler has scored.                                                                                                               |
| **Reporting & export**          | Aggregate reporting — counts, trends, and a vulnerable-package inventory — plus asynchronous **CSV exports** of findings and other data (start an export, then poll for the download). |
| **Documentation**               | Search Heeler's published product documentation and return relevant excerpts with links.                                                                                               |

Almost all of these are **read-only** — the agent observes, it doesn't change your platform. Two capabilities sit behind a stricter gate: SLO overrides and triggering agentic remediation. Both require the **Administrator** role *plus* a write or execute scope; a read-only or scan-only connection can't use them (see [Scopes and access](#scopes-and-access)).

The connection is a single Model Context Protocol endpoint (Streamable HTTP). Heeler exposes everything as **tools** and **prompts** — there are no MCP *resources* to mount.

{% hint style="info" %}
This page describes the **categories** of context. The complete, exact list of tool names — with parameters — lives in [**MCP Tools and Prompts**](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md), so there's one catalog to maintain.
{% endhint %}

## Scoping a question to a repository

Most tools identify a repository by `repository_id`. The project tools — service risk brief, file-level SAST results, project vulnerabilities, endpoint security context and deployment exposure — also take a full `repository_url` and resolve it across **GitHub, GitLab, Bitbucket, and Azure DevOps**, so the same ask works whatever SCM you're on.

Name the repository in your ask; the agent passes it in whichever field the tool accepts. Where a name matches more than one repository, Heeler returns the candidates to choose from. The exact fields per tool are in [MCP Tools and Prompts](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md).

### Editor context vs. chat-first clients

In **editor-based** clients — Cursor, Windsurf, Zed, and compatible VS Code extensions — Heeler receives your current file path and repository URL, so *"check SAST findings for the file I'm on"* resolves without manual scoping. In **chat-first** clients like Claude.ai there's no active editor context, so scope explicitly by URL: *"Check SAST findings for `https://github.com/org/repo`."* Heeler resolves the URL regardless of provider.

## Built-in prompts

Beyond tools, the server ships **named prompts** — repeatable, structured security reviews you invoke by name so every developer runs the same rigorous pass:

| Prompt                         | What it runs                                                                |
| ------------------------------ | --------------------------------------------------------------------------- |
| `secure_development_checklist` | A pre-commit secure-development pass over the code in hand.                 |
| `secure_code_risk_review`      | A focused risk review of a change — what could go wrong and what to verify. |
| `heeler_sast_pass`             | A SAST-oriented review that pulls and reasons over code-security findings.  |
| `heeler_sca_dependency_guard`  | A dependency check that surfaces and triages vulnerable packages.           |

Invoke a prompt by its exact name — paraphrases may not resolve. Full detail is in [MCP Tools and Prompts](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md#built-in-prompts).

## Common workflows

Each is triggered with a single natural-language ask — the assistant orchestrates the tool calls:

| Workflow                             | What the assistant does                                                                                                                                       |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pre-PR security pass**             | Runs `secure_development_checklist`, then pulls SAST + dependency + endpoint context for the changed code and summarizes what to fix before you open the PR.  |
| **New endpoint review**              | When you add an endpoint, runs the secure-development checklist and reviews auth, input validation, and exposure for the new route.                           |
| **Runtime exposure triage**          | Uses the deployment-exposure and service-risk tools to tell you which findings are actually internet-accessible and running — so you triage by real exposure. |
| **File-level SAST remediation loop** | Pulls SAST results for the file you're editing, then fixes findings one file at a time without leaving the editor.                                            |

## Pair platform context with a working-tree scan

MCP reads the security, architecture, policy, and runtime context Heeler has stored from committed code and connected environments. It does not scan uncommitted files in your working tree. Before committing, pair MCP context with `heelercli ci` or the [Agent Skills](/mrecEO40m5D6bt7Pq5pE/prevent/agent-skills.md) so the agent evaluates the exact local change as well as the system it will enter.

The built-in `secure_development_checklist` prompts the agent to do both: use MCP for stored context, then run the CLI or skills over the working tree.

## Scopes and access

The read tools (and the prompts) unlock with `heeler:read`; the write tools each need an additional scope **and** the **Administrator** role:

| Scope                         | Unlocks                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `heeler:read`                 | Every read-only tool, plus the built-in prompts. Sufficient on its own for all read access.                   |
| `heeler:scan:vulnerabilities` | An alternative to `heeler:read` on the finding, vulnerability and guardrail tools; not sufficient on its own. |
| `heeler:write:overrides`      | SLO overrides *(Administrator only)*.                                                                         |
| `heeler:execute:remediation`  | Trigger agentic remediation *(Administrator only)*.                                                           |

Grant `heeler:read` for the everyday experience — it covers the whole read surface, and `heeler:scan:vulnerabilities` adds nothing on top of it. Scopes are granted over OAuth, which is how a client reaches the tools. The full flow and per-client config are in [Connect the MCP Server](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/mcp.md).

Over MCP, triggering a remediation needs the **Administrator** role. A **Team contributor** or **Organization contributor** can trigger one in the web interface.

## Predictable errors and throttling

The server validates every tool call against the same input schema it advertises. Tool-call failures return an MCP `isError` result with a stable code — `invalid_arguments`, `not_found`, `conflict`, `tool_error`, or `internal_error` — and a `request_id` you can give Heeler support to correlate with server logs. Unexpected internal details stay out of the response.

A role that is not permitted returns HTTP `403` with an `access_denied` OAuth challenge, which only a change of role resolves.

A missing scope on a tool call returns HTTP `403` with an `insufficient_scope` challenge naming the scope, which a client that supports incremental authorization can request. Listing tools or prompts with a missing scope returns a JSON-RPC error in an HTTP `200` response instead.

Authenticated OAuth and browser-session MCP traffic has a default budget of **600 calls per minute per verified principal**. Unverified traffic has a shared **60 calls per minute per source network** budget. A `429` includes `Retry-After` and the `X-RateLimit-*` headers. See [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) for identity, tenant overrides, and client behavior.

## Troubleshooting

* **The agent can't resolve a repository.** Your client isn't passing repo context — scope explicitly by URL: *"Check findings for `https://github.com/org/payments-api`."*
* **A prompt doesn't run.** Use the canonical prompt name exactly — `secure_development_checklist`, `secure_code_risk_review`, `heeler_sast_pass`, `heeler_sca_dependency_guard`. Paraphrases may not resolve.
* **Results scoped to the wrong place.** Ask Heeler to list matching teams/services first, then rerun with the confirmed exact name.
* **Write operations fail.** SLO-override and remediation tools need the **Administrator** role plus the write or execute scope; a read-only or scan-only token errors. Ask an administrator to change your role.
* **The server returns `429`.** Honour `Retry-After` before retrying. If normal interactive use reaches the authenticated-principal budget, send the response headers and `request_id` to Heeler so the tenant limit and call pattern can be reviewed.
* **Missing context in a chat client.** Chat-first clients have no editor context — provide the repository URL rather than referring to "the file I have open."
* **"No agent-file data."** Agent files aren't a finding type, so the findings tools return nothing for them, which is not an absence of risk. Ask for them by name: *"list the at-risk agent files"* routes to `agent_files_list`. See [Agent-file governance](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md#agent-file-governance).

## Related

* [Agent Skills](/mrecEO40m5D6bt7Pq5pE/prevent/agent-skills.md) — run Heeler's scans in natural language in the same agent (the write-your-own-command counterpart to MCP's read context).
* [MCP Tools and Prompts](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md) — the full tool and prompt catalog.
* [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) — MCP principal budgets, response headers, and backoff.
* [Connect the MCP Server](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/mcp.md) — endpoints, OAuth scopes, and per-client setup.
* [Heeler in Slack](/mrecEO40m5D6bt7Pq5pE/operate/heeler-in-slack.md) — the same Heeler context and assistant, in Slack.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.