Superagent exposes its REST API as a remote Model Context Protocol server, so an AI coding agent can read findings, inspect reports, and start new security work without you writing any integration code.

https://www.superagent.sh/mcp

The server speaks Streamable HTTP and authenticates with the same organization API keys as the REST API.

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.

{
  "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

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.

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.

Available tools

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, Web app, and Agent 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 Web app
create_agent_report	Start billable adversarial testing against an AI agent through a Web app 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
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 API overview, Reports,
Findings,
Contributor Trust, and
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.

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."
• "Start an Agent report against https://agent.example.com/chat using the Web app target type."
• "Start an Agent API report against OpenRouter. Use model qwen/qwen3.7-flash, send a messages payload, and include my authorization header."

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

Next steps

• API overview
• Reports API
• Findings API
• Contributor Trust API
• Webhooks