MCP Server | Superagent Docs

Connect Cursor, Claude Code, or Codex CLI to Superagent over the Model Context Protocol.

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 and Web app 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

Each tool mirrors the equivalent REST endpoint, so the arguments and returned fields match the Reports and Findings references. Responses include both readable text and structured JSON.

Tools that cost money or destroy data

create_repository_report, create_web_app_report, and triage_finding all consume organization credits. delete_finding is irreversible.

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

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`

Overview