superagent_

// interfaces

MCP

[ view markdown ]

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

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

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

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

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, Reports, Incidents, Findings, Contributor Trust, Historical Dependency Updates, Context Guardrails, Applications, Agents, and 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:

{
  "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 for the shared behavior and Findings API 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 on Dependabot and Renovate security PRs. The manual updater tool has been removed. See Historical 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

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 for the shared-memory workflow, hosted Superagent setup, and bring-your-own-database setup.

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