> 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/get-started/set-up-developer-tooling/mcp.md).

# Connect the MCP Server

Connect an AI coding agent to Heeler's MCP server so it can pull live, read-only security context as it writes code.

The Heeler **MCP server** exposes structured security tools to any MCP-compatible client, so an agent can consult Heeler as it writes. This page connects a client; for what the tools do and how to use them, see [Prevent → MCP Server](/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md).

Clients that run on your machine — Claude Code, Codex CLI, Cursor and other OpenCode-style clients — sign in through a local callback. Heeler also accepts the sign-in callbacks of the hosted clients: **Claude**, **ChatGPT connectors**, **Cursor**, **Notion Custom Agents** and **VS Code**.

## Prerequisites

* An active **Heeler account** at [app.heeler.com](https://app.heeler.com).
* An **MCP-compatible client** — Claude Code, Claude, ChatGPT connectors, Cursor, Codex CLI, VS Code, a Notion Custom Agent, or another OpenCode-style client.
* **Network access** to `https://app.heeler.com` (TCP 443) from wherever the client runs.

## Endpoints

<table><thead><tr><th width="250">Endpoint</th><th>URL</th></tr></thead><tbody><tr><td>Base URL</td><td><code>https://app.heeler.com</code></td></tr><tr><td>MCP RPC</td><td><code>https://app.heeler.com/mcp</code></td></tr><tr><td>OAuth protected-resource metadata</td><td><code>https://app.heeler.com/.well-known/oauth-protected-resource</code></td></tr><tr><td>OAuth authorization-server metadata</td><td><code>https://app.heeler.com/.well-known/oauth-authorization-server</code></td></tr><tr><td>RFC 8414 MCP compatibility alias</td><td><code>https://app.heeler.com/.well-known/oauth-authorization-server/mcp</code></td></tr></tbody></table>

Clients normally discover these metadata documents automatically from the MCP RPC URL; configure only `https://app.heeler.com/mcp` unless your client explicitly asks for a metadata URL.

## Authentication and scopes

OAuth is recommended — most clients handle the flow natively when you add the server URL. **`heeler:read` is the only scope the read-only tools need**, and it covers the full read surface on its own:

<table><thead><tr><th width="320">Scope</th><th>Purpose</th></tr></thead><tbody><tr><td><code>heeler:read</code></td><td>Every read-only tool, plus the built-in prompts. Sufficient by itself for all read access.</td></tr><tr><td><code>heeler:scan:vulnerabilities</code></td><td>An <em>alternative</em> to <code>heeler:read</code> on the finding, vulnerability and guardrail tools — typically issued to automated scanners. It grants nothing that <code>heeler:read</code> doesn't, and on its own it is <strong>not</strong> enough: <code>docs_search</code>, the CSV export tools and the built-in prompts all require <code>heeler:read</code> specifically.</td></tr></tbody></table>

Two more scopes gate the **write** tools, and each also needs the **Administrator** role — **Administrator (read-only)** is not granted them: `heeler:write:overrides` (SLO overrides) and `heeler:execute:remediation` (agentic remediation). Full detail: [MCP Tools and Prompts → Scopes](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md#scopes).

Scopes are granted over OAuth, which is how a client reaches the tools. A Heeler API key carries no scopes: sent as a bearer token it completes the connection handshake and reaches no tool.

{% hint style="info" %}
Heeler's authorization server also advertises `heeler:scan:licenses`, `heeler:scan:malicious_packages`, `heeler:scan:secrets` and `heeler:scan:sbom`, so your client may request them and the consent screen may list them. Those cover the CLI and REST API — they grant no MCP access, and MCP needs none of them.
{% endhint %}

## Connect a client

{% tabs %}
{% tab title="Claude Code" %}

```bash
claude mcp add --transport http heeler https://app.heeler.com/mcp
claude
```

Then type `/mcp`, select **heeler**, and complete OAuth sign-in.
{% endtab %}

{% tab title="Cursor" %}
Add the server to `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "heeler": {
      "url": "https://app.heeler.com/mcp"
    }
  }
}
```

Then authorize: in the IDE open **Settings → MCP** and approve the OAuth prompt, or from the Cursor CLI run

```bash
cursor-agent mcp login heeler
```

`cursor-agent mcp list` reports `requires_authentication` until that completes; `cursor-agent mcp list-tools heeler` lists the tools once it has.
{% endtab %}

{% tab title="Codex CLI" %}

```bash
codex mcp add heeler --url https://app.heeler.com/mcp
```

Adding the server starts the OAuth flow straight away — complete the browser sign-in, then confirm with `codex mcp list`, where **heeler** should report `Auth: OAuth`. To re-authenticate later, run `codex mcp login heeler`.

Codex keeps its configuration in `~/.codex/config.toml` as **TOML**, so to add the server by hand:

```toml
[mcp_servers.heeler]
url = "https://app.heeler.com/mcp"
```

No `auth` entry is needed — Codex starts the OAuth flow from the server's authentication challenge.

Other OpenCode-style clients use the same URL but their own configuration format and connect command; check your client's MCP documentation.
{% endtab %}

{% tab title="Notion" %}
Notion Custom Agents connect through Notion's own UI; there is no config file.

1. Open the Custom Agent and select **Tools & Access**.
2. Select **Add connection → Custom MCP server**.
3. Enter `https://app.heeler.com/mcp` as the **MCP server URL** and **Heeler** as the **Name**.
4. Keep **Authentication** on **OAuth** and select **Connect**.

Notion registers with Heeler, then opens the Heeler sign-in and consent screen. Approve the requested scopes to finish. Notion shows a **Notion hasn't reviewed this server** warning for every custom MCP server; it does not indicate a problem with the connection.
{% endtab %}
{% endtabs %}

## Supported repositories

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**. The exact fields each tool takes are in [MCP Tools and Prompts](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md).

## Verify

In your client, type `/mcp` — **heeler** should show as **connected** with its tools listed. Then try one prompt to confirm the agent can reach Heeler, for example *"What are the open critical findings for `https://github.com/org/repo`?"* — you should get results drawn from Heeler rather than a "no server" or auth error.

## Troubleshooting

<table><thead><tr><th width="300">Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>The agent can't resolve a repository</td><td>Your client isn't passing repo context. Name the repository in the ask, e.g. <em>"Check findings for <code>https://github.com/org/repo</code>."</em> Heeler looks the name up and returns candidates when more than one matches.</td></tr><tr><td>Write operations fail</td><td>SLO-override and remediation tools need the <strong>Administrator</strong> role plus the write or execute scope. A <strong>Team contributor</strong> or <strong>Organization contributor</strong> can trigger a remediation in the web interface but not over MCP, and gets <code>access_denied</code>. <strong>Administrator (read-only)</strong> is never issued these scopes, so they do not appear on its consent screen.</td></tr><tr><td>A tool returns <code>invalid_arguments</code></td><td>The client sent a value that does not match the tool's advertised schema. Use the failing argument path in the message to correct the call; do not retry the same arguments.</td></tr><tr><td>The server returns <code>429</code></td><td>Wait for <code>Retry-After</code> before retrying. See <a href="/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md">Rate Limits</a> for MCP principal budgets and response headers.</td></tr><tr><td>Codex on WSL or headless Linux can't stay signed in</td><td>Codex keeps MCP OAuth tokens in the OS keyring and will not fall back to a file on its own, so hosts with no secret service fail with <code>org.freedesktop.secrets was not provided by any .service files</code>. Add <code>mcp_oauth_credentials_store = "file"</code> to <code>~/.codex/config.toml</code>, above the first <code>[table]</code> heading.</td></tr><tr><td>Missing context in a chat client</td><td>Chat-first clients (e.g. Claude.ai) have no editor context — provide the repository URL rather than "the file I have open."</td></tr><tr><td>Notion reports <em>Failed to set up OAuth client registration</em></td><td>Heeler accepts OAuth registration only from known hosted clients, and Notion is one of them. Confirm the server URL is exactly <code>https://app.heeler.com/mcp</code>, leave <strong>Authentication</strong> on <strong>OAuth</strong>, and retry. A header-based API key is not an alternative here: it authenticates the connection but reaches none of the tools.</td></tr></tbody></table>

## Related

* [Prevent → MCP Server](/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md) — editor-vs-chat context, common workflows, and the tool catalog.
* [MCP Tools and Prompts](/mrecEO40m5D6bt7Pq5pE/reference/mcp-tools-and-prompts.md) — the full tool and prompt reference.
* [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) — authenticated and anonymous MCP budgets, headers, and retry behavior.


---

# 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/get-started/set-up-developer-tooling/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.