// interfaces
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/mcpThe 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 superagentThe 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/serversand 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/chatusing the application target type." - "Start an Agent API report against OpenRouter. Use model
qwen/qwen3.7-flash, send amessagespayload, 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 againsthttps://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.