> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Connect an agent to Superagent, use security tools, and return structured agent reports.

# MCP

Superagent exposes its REST API as a remote [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI coding agent can read findings, inspect reports, and start new security work without you writing any integration code.

```text
https://www.superagent.sh/mcp
```

The server speaks Streamable HTTP and authenticates with the same organization API keys as the REST API. The key determines your organization; no organization ID or extra organization header is required. It supports the current `2026-07-28` protocol with server discovery and per-request metadata, and continues to accept legacy clients that initialize with `2025-11-25`.

## Guided setup with the Superagent skill

Install the Superagent skill, then ask your coding agent to connect:

```bash
npx skills add superagent-ai/skills --skill superagent
```

The skill supports Cursor, Claude Code, Codex CLI, and other MCP clients. It protects your API key, shows the proposed configuration before changing it, and verifies that the connection exposes Superagent tools. See the [docs overview](https://www.superagent.sh/docs) for the complete flow.

## Authentication

Create a key under **Settings** (`/app/settings#api-keys`) and send it as a bearer token. An API key grants access to everything in its organization, including permanently deleting findings and starting billable report and triage work, so treat it like a password and revoke it if it leaks.

Store the key in an environment variable rather than pasting it directly into a config file that you might commit.

## Connect your client

### Cursor

Add the server to `mcp.json`. Cursor infers the remote transport from the presence of `url`, so no `type` key is needed.

```json
{
  "mcpServers": {
    "superagent": {
      "url": "https://www.superagent.sh/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SUPERAGENT_API_KEY}"
      }
    }
  }
}
```

Remote servers do not read `envFile`, so `SUPERAGENT_API_KEY` must be set in your shell profile or system environment.

### Claude Code

```bash
claude mcp add --transport http --scope user superagent https://www.superagent.sh/mcp \
  --header "Authorization: Bearer $SUPERAGENT_API_KEY"
```

Run `/mcp` inside a session to confirm the server connected and is listing tools.

### Codex CLI

Add the server to `~/.codex/config.toml`. The `experimental_use_rmcp_client` flag enables Streamable HTTP support and **must appear above** every `[mcp_servers.*]` block — Codex silently fails to connect if it is missing or placed after them.

```toml
experimental_use_rmcp_client = true

[mcp_servers.superagent]
url = "https://www.superagent.sh/mcp"
bearer_token_env_var = "SUPERAGENT_API_KEY"
```

`bearer_token_env_var` takes the *name* of an environment variable, not the token itself, and the variable must be exported before you launch Codex. Verify with `/mcp` in a session.

## Security tools

Your MCP client shows the current tool names and input schemas, including the operation for returning a structured agent report. Use that generated schema rather than adding fields in prompts or configuration.

Finding comment tools are handled natively by Security Graph when the connected deployment supports them. Comments share the same discussion as the dashboard. Supply an `idempotency_key` to retry writes safely, and use the comment’s `version` as `expected_version` for edits and deletion. Existing App MCP comment inputs remain supported; direct Security Graph clients must provide these mutation fields.

| Tool | Description |
| --- | --- |
| `list_incidents` | List infrastructure incidents by status, resolution, severity, source, environment, group, and search text |
| `get_incident` | Retrieve incident assessment, evidence, review history, and recent webhook deliveries |
| `update_incident_triage` | Update incident review status using its current version; records the API key actor |
| `list_findings` | List and filter findings by kind and triage status |
| `get_finding` | Retrieve full triage, remediation, and report context for a finding |
| `list_finding_comments` | List a finding's comments, newest first, with `limit` and `offset` |
| `create_finding_comment` | Add attributed Markdown review context to a finding and its Security Graph discussion |
| `update_finding_comment` | Replace a comment's body using `finding_id`, `comment_id`, and `body` |
| `delete_finding_comment` | Permanently delete a comment using `finding_id` and `comment_id` |
| `update_finding_triage` | Update a finding's manual triage state |
| `triage_finding` | Start billable automated triage for a finding |
| `delete_finding` | Permanently delete a finding |
| `list_reports` | List and filter repository, application, Agent, Package, and Image reports |
| `get_report` | Retrieve one report by identifier |
| `list_image_connections` | List configured AWS/GCP connections without credentials |
| `discover_images` | Discover repositories through an existing connection |
| `list_images` | List monitored images with pagination and search |
| `get_image` | Read image settings and configured variable names |
| `create_image` | Add monitoring through an existing connection |
| `update_image` | Partially update image settings while preserving omitted values |
| `delete_image` | Remove monitoring while retaining reports and the cloud image |
| `refresh_image` | Queue a registry/advisory refresh |
| `list_image_versions` | List image digests, tags, platform and scanner status |
| `list_image_advisories` | Filter current advisories by version, severity, exposure or search |
| `create_image_report` | Start billable advisory validation with an idempotency key |
| `list_image_report_events` | Read paginated execution progress and logs |
| `cancel_image_report` | Cancel validation and clean up its sandbox |
| `delete_image_report` | Delete a validation report and its events after cleanup |
| `update_report_review_status` | Mark a successfully finished report Completed or return it to In Review |
| `create_repository_report` | Start a billable report for a connected GitHub repository |
| `create_web_app_report` | Start a billable report against a public application |
| `create_agent_report` | Start billable adversarial testing against an AI agent through an application or API |
| `create_package_report` | Start billable black-box testing against installable software using installation instructions |
| `get_contributor_trust` | Retrieve the latest globally cached Contributor Trust result for a GitHub username |
| `scan_contributor_trust` | Start an asynchronous Contributor Trust scan for a GitHub username |
| `get_contributor_trust_scan` | Retrieve an organization-scoped Contributor Trust scan by ID |
| `get_dependency_update` | Read an organization-scoped historical dependency update run |
| `get_context_score` | Score a web page before an agent consumes it |
| `scan_email` | Score a raw RFC 822 email before an agent consumes it |
| `scan_message` | Score SMS or WhatsApp text and outbound links before an agent consumes it |
| `scan_file` | Score a public text or PDF file before an agent consumes it |
| `scan_skill` | Statically score a skills.sh or GitHub hosted agent skill |
| `scan_mcp` | Statically score a public GitHub MCP repository without connecting to or executing it |
| `scan_package` | Score a registry package with the same supply chain pipeline used on pull requests |
| `list_applications` | List persistent Application assets and red-team settings |
| `get_application` | Retrieve one Application and its configuration |
| `create_application` | Create an Application with a live URL and optional repository |
| `update_application` | Update Application identity, credentials, throttle, schedule, or prompt |
| `list_application_inventory` | List discovered assets and the latest Application discovery run |
| `discover_application_inventory` | Start C99-backed Application asset discovery |
| `update_application_inventory_asset` | Include, exclude, or mark a discovered asset unverified |
| `list_agents` | List persistent Agent assets and runtime connections |
| `get_agent` | Retrieve one Agent and its red-team configuration |
| `create_agent` | Create an Agent; Coding Agents receive one-time pairing details |
| `update_agent` | Update Agent identity, repository reference, target, credentials, schedule, or prompt |
| `list_agent_clients` | List registered endpoint clients |
| `get_agent_client` | Retrieve one endpoint client |
| `create_agent_client` | Register a client and return a pairing token |
| `update_agent_client` | Rename an endpoint client |
| `revoke_agent_client` | Revoke a client and its credentials |
| `create_agent_pairing_token` | Generate a new one-time pairing token |
| `set_agent_client_groups` | Replace a client's group memberships |
| `list_agent_groups` | List client groups and assignments |
| `get_agent_group` | Retrieve one client group |
| `create_agent_group` | Create a client group |
| `update_agent_group` | Update a client group |
| `delete_agent_group` | Delete a client group |
| `set_agent_group_rules` | Replace a group's security rules |
| `set_agent_group_builtin_rules` | Replace a group's built-in rule exclusions |
| `list_agent_builtin_rules` | List pinned built-in rules and effective modes |
| `get_agent_builtin_rule` | Retrieve one built-in rule and its override state |
| `set_agent_builtin_rule_mode` | Set a built-in rule to monitor, enforce, or disabled |
| `restore_agent_builtin_rule` | Restore a built-in rule's shipped default |
| `list_agent_rules` | List YAML security rules |
| `get_agent_rule` | Retrieve one YAML security rule |
| `create_agent_rule` | Create and assign a security rule |
| `update_agent_rule` | Replace a rule and its assignments |
| `delete_agent_rule` | Delete a security rule |
| `validate_agent_rule` | Validate YAML with Numbat without saving |
| `generate_agent_rule` | Generate and validate YAML with Kimi K3 |
| `list_agent_alerts` | List endpoint findings and enforcement decisions |
| `get_agent_alert` | Retrieve privacy-filtered unified alert detail |
| `list_telemetry_endpoints` | List OpenTelemetry log destinations |
| `get_telemetry_endpoint` | Retrieve one OpenTelemetry destination |
| `create_telemetry_endpoint` | Create an OpenTelemetry destination with a public OTLP endpoint |
| `update_telemetry_endpoint` | Update an OpenTelemetry destination |
| `delete_telemetry_endpoint` | Permanently delete an OpenTelemetry destination |
| `test_telemetry_endpoint` | Send a synthetic OTLP log event to a destination |

Each tool mirrors the equivalent REST endpoint, so the arguments and returned
fields match the [REST API](https://www.superagent.sh/docs/api), [Reports](https://www.superagent.sh/docs/api/reports),
[Incidents](https://www.superagent.sh/docs/api/incidents),
[Findings](https://www.superagent.sh/docs/api/findings),
[Contributor Trust](https://www.superagent.sh/docs/api/contributor-trust),
[Historical Dependency Updates](https://www.superagent.sh/docs/api/dependency-updates),
[Context Guardrails](https://www.superagent.sh/docs/api/context-guardrails),
[Applications](https://www.superagent.sh/docs/api/applications),
[Agents](https://www.superagent.sh/docs/api/agents), and
[Telemetry](https://www.superagent.sh/docs/api/telemetry) references.
Responses include both readable text and structured JSON.

### Report review status

Use `update_report_review_status` to change review status for a repository, application, Agent, or Package report:

```json
{
  "report_id": "1696f465-7903-4eaf-8bc9-a457bc024ff7",
  "status": "completed"
}
```

Set `status` to `in_review` to reopen review. Only successfully finished reports can change review status; running and failed scans return a `conflict` error. Reports outside the API key's organization return `not_found`.

Completing review is allowed with unresolved findings and does not change scan execution or individual finding resolutions. The tool returns the updated report. Use `get_report` to retrieve it later, or `list_reports` with `status: "completed"` to find completed reviews.

Resolving all findings through `update_finding_triage` also completes a report automatically. New or reopened unresolved findings return it to In Review. See [Reports API](https://www.superagent.sh/docs/api/reports#update-report-review-status) for the shared behavior and [Findings API](https://www.superagent.sh/docs/api/findings) for resolution values.

### Other tool behavior

`scan_contributor_trust(username)` requires an active Superagent GitHub App
installation and an enabled registered webhook subscribed to
`contributor_trust.finished`. Use `get_contributor_trust_scan(scan_id)` to check
the organization-scoped status or wait for the completion webhook.
`get_contributor_trust(username)` reads the global cache and returns an error
when no result exists.

`get_dependency_update(run_id)` reads an organization-scoped historical updater run.
New assessments run through [Dependency Validation](https://www.superagent.sh/docs/products/dependency-validation)
on Dependabot and Renovate security PRs. The manual updater tool has been removed.
See [Historical Dependency Updates](https://www.superagent.sh/docs/api/dependency-updates) for legacy reads.

`scan_email` accepts the original RFC 822 message and preserves the headers,
MIME structure, and attachment metadata used by the full email scan.
`scan_message` accepts SMS and WhatsApp message text plus optional
channel and outbound link fields.

`scan_mcp(target, details?, mode?)` accepts `owner/repository` or
`https://github.com/owner/repository` with an optional `.git` suffix. Set
`details` to include subscores and all threats, and set `mode` to `full` to wait
for all scan tiers. The organization must have the Superagent Security GitHub
App installed. Only public repositories are supported. The bounded scan reads
at most 200 files, 512 KB per file, and 2 MB total. It treats every file as
untrusted data, never opens an MCP connection, never executes repository code,
and fails closed when the repository cannot be scanned.

`scan_package(target, details?, mode?)` accepts `ecosystem:name@version`, for
example `npm:lodash@4.17.21`. Set `details` to include subscores and all
threats, and set `mode` to `full` to wait for the scan. Supported ecosystems
are npm, PyPI, Go, RubyGems, and GitHub Actions. The scan uses the same
managed supply chain pipeline as pull request dependency checks and fails
closed when package intelligence cannot be collected.

MCP returns alert snapshots through `list_agent_alerts` and `get_agent_alert`.
Long-lived live logs are available only through the REST
`GET /api/v1/agents/logs/stream` SSE endpoint.

Generic per-user Notifications and notification preferences are intentionally
excluded. Organization API keys cannot act as an individual notification
recipient; durable Agent alerts are the programmatic monitoring surface.

### Tools that cost money or destroy data

`create_repository_report`, `create_web_app_report`, `create_agent_report`, `create_package_report`, and `triage_finding` all consume organization credits. `delete_finding` is irreversible. Built-in mode changes and restoring shipped defaults alter endpoint policy immediately, so those tools also request confirmation.

These are annotated so MCP clients can prompt before running them, but annotations are only hints and enforcement varies by client. Review your client's tool-approval settings before giving an agent unattended access, and prefer a separate key you can revoke independently.

## Example prompts

Once connected, you can work in plain language:

- "List the unresolved high-risk findings in Superagent."
- "Show me the details of the newest finding and explain the root cause."
- "Mark finding `<id>` as a false positive."
- "Did the last repository report on acme/web finish?"
- "Show the latest Contributor Trust result for octocat."
- "Scan contributor octocat, then check the scan status."
- "Statically scan the MCP repository `modelcontextprotocol/servers` and include all threat details."
- "Score the npm package lodash@4.17.21 before I install it."
- "Start an Agent report against `https://agent.example.com/chat` using the application target type."
- "Start an Agent API report against OpenRouter. Use model `qwen/qwen3.7-flash`, send a `messages` payload, and include my authorization header."
- "Create a Coding Agent called Production and associate it with repository ID `1095278383`."
- "Configure Agent `<id>` for weekly browser red teaming against `https://agent.example.com`."

## Rate limits

Requests are limited per API key per minute. Exceeding the limit returns HTTP `429` with a `Retry-After` header. Agents that retry aggressively are the usual cause, so prefer a single tool call over repeated polling.

## Troubleshooting

Use `https://www.superagent.sh/mcp`, not the bare `superagent.sh` domain — the bare domain redirects to `www`, and some MCP clients do not follow the redirect on POST, which surfaces as a connection failure rather than a clear error.

| Symptom | Cause |
| --- | --- |
| `401 invalid_token` | Missing, malformed, or revoked key; the header must read `Authorization: Bearer sk_live_...` |
| `404` or "Failed to connect" against `superagent.sh/mcp` | The bare domain redirects to `www`; point the client at `https://www.superagent.sh/mcp` directly |
| Server connects but lists no tools | The key is valid but authentication is being stripped by a proxy; check the header reaches the server |
| Codex shows the server as unavailable | `experimental_use_rmcp_client = true` is missing, or sits below the `[mcp_servers.*]` blocks |
| Codex reports a missing token | `bearer_token_env_var` holds a literal token instead of an environment variable name |
| `429` responses | Rate limit reached; back off and retry after the interval in `Retry-After` |

## Return structured agent reports

After a customer agent investigates, remediates, or records a disposition, it
returns a structured agent report through Superagent MCP. Superagent retains
the report as customer context and applies the accumulated context to
subsequent work across protected software and products.

Use the structured report operation and schema exposed by the connected Superagent MCP server. Do not invent fields in prompts or client configuration.

## Next steps

- [Subscribe to events with Webhooks](https://www.superagent.sh/docs/webhooks)
- [Understand findings and reports](https://www.superagent.sh/docs/concepts/findings-and-reports)
- [Connect another agent](https://www.superagent.sh/docs/connect/other-agents)

For infrastructure review, call `get_incident` first and pass its `triage_version`
to `update_incident_triage`. A stale version returns a `conflict` tool error.
Resolving requires `fixed`, `accepted_risk`, `false_positive`, or `wont_fix`;
reopening uses `new` or `in_review` with a null resolution.

## Security Graph tools

Superagent's hosted MCP connection also exposes Security Graph's shared security context. Connect with your organization API key; Superagent manages the graph service and storage. Every graph tool requires an `intent`: a short explanation of the security task the call supports, without secrets.

See the [Security Graph guides](https://www.superagent.sh/docs/security-graph) for the shared-memory workflow, [hosted Superagent setup](https://www.superagent.sh/docs/security-graph/superagent), and [bring-your-own-database setup](https://www.superagent.sh/docs/security-graph/bring-your-own-database).

| Tool | Description |
| --- | --- |
| `list_assets` | Discover assets already represented by reports and connected repositories |
| `get_context` | Retrieve related assets, reports, findings and evidence with bounded graph traversal |
| `get_neighbors` | Page through an authorized record's connections |
| `create_asset` | Register an asset for external security work |
| `create_report` | Record an external assessment using the unified report interface |
| `submit_finding` | Submit a finding using the existing structured finding template |
| `finish_report` | Finish an assessment created by the same API key |
| `add_relationship` | Link relevant security records with provenance |
| `list_changes` | Read change metadata for graph-mediated mutations |
| `get_vulnerability_catalog` | Discover curated technical types and framework mappings |
| `get_finding_classification` | Read a finding's current attributed classification |
| `get_classification_options` | Read selectable vulnerability types and compliance entries |
| `set_finding_classification` | Save the agent’s selections from both lists with rationale |

`create_report` records work performed by your own agent and model. The existing `create_repository_report`, `create_web_app_report`, `create_agent_report`, and `create_package_report` tools start Superagent security work.

The finding template has six sections: Impact, Details, Policy Verification, Code References, PoC, and Remediation. Provide concrete reproduction evidence and remediation guidance. Source references, policy documents, and a validated patch are supported when available; black-box submissions must explain unavailable references and policy documents using the required reason fields. New submissions enter triage as **New**; the supplied evidence does not independently verify a vulnerability.

Use a stable `idempotency_key` when retrying a write. Updates to findings and report review also require the `expected_version` returned by a fresh read. Graph list tools use stable ID pagination through `after`; the app envelope provides `pagination.next_after`. Use the live tool schemas for their filters and current required fields.

### Vulnerability types and compliance

Use `get_classification_options` with `query` or `limit` to search two named lists:
`vulnerability_types` and `compliance`. Follow `next_cursor` with the same filters
and limit. Each choice has a stable catalog ID and a name; the response also
includes the catalog version, descriptions, framework releases, coverage metadata,
and reference mappings. The MCP service owns the catalog; App retrieves its
definitions automatically rather than maintaining its own vocabulary.

The agent reviewing the evidence selects IDs from both lists and calls
`set_finding_classification`. Supply `finding_id`, current `expected_version`,
`expected_classification_version` (0 initially), the returned `catalog_version`, `type_ids`, `compliance_ids`,
a concise `rationale`, `intent`, and a stable `idempotency_key`. Both arrays are
required. Use an empty array when no catalog choice applies. The service validates
IDs against the selected catalog release; invented or duplicate IDs and stale writes are rejected.
Read the assignment with `get_finding_classification`.

Selections are saved as `agent_asserted`, with their rationale and provenance.
The hosted MCP does not run Julia-1 or automatic inference. Explicit compliance
selections are retained independently of catalog reference mappings. They express
relevance, not certification, and never change finding verification, triage,
resolution or report review state.

### Shared memory in Superagent scans

With Security Graph enabled, Superagent's native repository, web app, agent,
package and PR scanners receive a scoped `security-graph` MCP connection. Scanners are
instructed to read prior evidence and reviewer decisions before assessment and
search relevant history before reporting candidates. `search_context` searches findings and PR
feedback, including older records beyond the startup snapshot; `get_context`
reads matching records and their dismissal or remediation evidence. The run
selects the organization and asset automatically.

Scanners save confirmed findings through their guarded native finding/result
tools, which persist through Security Graph MCP. Each publishing agent must
successfully search history before saving. Agents read `get_classification_options` and include both selected ID lists and
rationale in each finding or PR receipt. The graph validates and saves those
selections in the same transaction. These selections, subsequent triage changes
and PR review feedback become
available to later assessments immediately. A clean rescan can replace findings
while preserving durable reviewer feedback. No second graph submission is needed.

Historical findings, accepted risks and dismissals are evidence to reassess
against current code and deployment conditions. They do not automatically confirm
or suppress an issue. Category selections also require evidence-based review.

## Image validation

The [Images API guide](https://www.superagent.sh/docs/api/images) describes the matching MCP inputs and
workflow: discover existing registry connections, monitor/configure an image, list
versions and advisories, then call `create_image_report`. Reuse `idempotency_key`
for retries and read progress through `get_report` and `list_image_report_events`.
Image report reads use the same canonical App serializers as REST even when
Security Graph is connected. Public environment reads include variable names,
not secret values; registry credentials stay in Integrations.

---
Source: https://www.superagent.sh/docs/mcp
Index: https://www.superagent.sh/llms.txt
