> 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.

## 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.

| Tool | Description |
| --- | --- |
| `list_findings` | List and filter findings by kind and triage status |
| `get_finding` | Retrieve full triage, remediation, and report context for a finding |
| `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, and Package red-team reports |
| `get_report` | Retrieve one report by identifier |
| `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_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 |

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),
[Findings](https://www.superagent.sh/docs/api/findings),
[Contributor Trust](https://www.superagent.sh/docs/api/contributor-trust),
[Context Guardrails](https://www.superagent.sh/docs/api/context-guardrails),
[Applications](https://www.superagent.sh/docs/api/applications), and
[Agents](https://www.superagent.sh/docs/api/agents) references.
Responses include both readable text and structured JSON.

`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.

`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 security workers.

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)

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