MCP server
Affectra serves your organization’s data as Model Context Protocol tools. Connect an AI assistant shows how to set one up. This page is the reference.
Address and credentials
Section titled “Address and credentials”| Address | Credentials |
|---|---|
https://api.affectra.eu/v1/orgs/{org}/mcp |
A person’s sign-in through an assistant, or an API key of that organization |
https://api.affectra.eu/v1/mcp |
An API key. The key names the organization. |
Send the credential as Authorization: Bearer …. The app’s browser session is refused. Without a credential, the organization’s address answers 401 with a WWW-Authenticate header that points the assistant to Affectra’s sign-in.
Protocol
Section titled “Protocol”- Streamable HTTP, without sessions: one JSON-RPC 2.0 request per
POST, answered withapplication/json.GETanswers405. No batches. - Protocol version
2026-07-28: every request carries the version and the client’s capabilities inparams._meta, and the headersMCP-Protocol-Version,Mcp-Methodand, fortools/callandprompts/get,Mcp-Name. A missing header, or one that doesn’t match the request, answers400with error-32020. A version Affectra doesn’t serve answers400with error-32022and the versions it serves. - Methods:
server/discover,tools/list,tools/call,prompts/listandprompts/get. Any other method answers404. - Assistants that start with
initializestill work: Affectra also serves versions2025-11-25and2025-06-18, withinitialize,pingand the same tool and prompt methods. - Requests up to 64 KiB.
- Requests from a web page (with an
Originheader) answer403, unless your deployment allows that origin. Assistants and agents send noOrigin. tools/listandprompts/listlist only the tools and prompts your role may use.
Every tool answers with structuredContent and a short text. The tools that read the graph answer with its nodes and edges, a summary, and truncated when a limit cut the answer.
| Tool | What it does | Lowest role | Counts against |
|---|---|---|---|
blast_radius |
The releases and units a vulnerability reaches, through which component, with the VEX status, KEV and EPSS. Takes vulnerability. |
Viewer | traversal |
describe_ontology |
The classes, properties and relations of the graph, and the parameters and limits of each tool that follows them. | Viewer | traversal |
explain_finding |
The dependency paths from an SBOM’s root to the component that matches a vulnerability, for a release or a unit, the vulnerability’s EUVD IDs and the vendor advisories that name its CVEs. When another advisory for the same CVE excludes the component’s version, the answer has an excludedBy edge with the fixed version, and conflict is true. Takes vulnerability, and release or unit; or a finding ID as finding. |
Viewer | traversal |
find_releases |
Releases by product name, variant and version, to get from a name such as edge-gateway v1.2 to the release the other tools take. | Viewer | traversal |
get_node |
One node by its ID, such as a release, a finding or CVE-2024-1234. Takes id. |
Viewer | traversal |
get_proposal |
A proposal’s status, who decided it and the reviewer’s note. Takes id. |
Viewer | traversal |
list_events |
What changed in your organization: new, known exploited and resolved findings, first matches and filed proposals of the last 30 days, oldest first, as webhooks get them. Takes optionally after (the next of the previous call), type and limit. See Events feed. |
Viewer | traversal |
list_feeds |
The vulnerability feeds and which ones your organization uses, with each feed’s state and who last changed it. Explains why a CVE known elsewhere has no finding: a feed your organization turned off hides its findings. It only reads; admins turn feeds on and off in the app or the API. See Choose vulnerability feeds. | Viewer | traversal |
list_proposals |
Your organization’s proposals, newest first, 20 at a time: by default the pending ones, with their evidence and explanation. Takes optionally status, kind, release and cursor. |
Viewer | traversal |
neighbours |
The nodes one relation joins a node to, one page at a time. Takes id, relation, and optionally direction and cursor. |
Viewer | traversal |
propose_cpe_mapping |
Proposes that a package URL is known in the NVD under a CPE vendor and product. An admin decides. Takes purl, vendor, product and evidence. |
Member | write |
propose_unit_release_link |
Proposes that units reporting a version text run one of your releases. A member decides. Takes reported, release and evidence. |
Member | write |
propose_vex |
Proposes a VEX statement for a finding. A member decides. Takes release and vulnerability, or a finding ID as finding; status, basis, evidence, and the statement’s other fields. |
Member | write |
similar_assessments |
Statements on your other releases for the same vulnerability, with how closely each matches, and proposals for it that were rejected. Takes release and vulnerability, or a finding ID as finding. |
Viewer | traversal |
triage |
The finding groups of a product or a release, in a fixed order with the inputs of the order: known exploited, KEV due date, affected units, EPSS, CVSS. No risk score. A finding group is one CVE, however many advisories report it. Takes product or release, and optionally conflict. |
Viewer | traversal |
unassessed_findings |
A release’s finding groups without a current VEX statement, in the same order. Takes release, and optionally conflict. |
Viewer | traversal |
Admins and owners get what members get. With an API key, Read only counts as viewer and Can propose changes as member. See Roles.
The read tools carry the MCP hint readOnlyHint. list_events also records that your organization reads its events, so Affectra keeps producing finding events for it; it changes none of your data. The propose tools file a proposal and nothing else: the statement, mapping or link is written only when a person accepts it. A newer proposal for the same finding or version text replaces a pending one.
Finding groups and conflicts
Section titled “Finding groups and conflicts”triage and unassessed_findings return one item for each finding group, not for each advisory. Each item in summary.ranking has the group’s node (group), its finding ID (ref), the Finding node of its best-ranked advisory (finding), the CVE (vulnerability; for a group without a CVE, the advisory’s ID), the IDs of all its advisories (advisories, the best-ranked first) and the inputs of its rank. The counts in the summary (findings, known_exploited, unassessed) are numbers of groups. The nodes also hold the group and, through groups edges, the findings of its advisories.
Pass conflict as true to list only the groups whose sources disagree: another advisory for the same CVE names a component of the release but says its version is not affected. Leave it out, or pass false, for all groups. Use explain_finding on such a CVE to see both sides: the matches edges of the advisories that match, and the excludedBy edges of those that do not, each with the fixed_version the advisory names, when it does. A conflict does not resolve a finding. A statement on the CVE does. See Sources disagree.
Evidence
Section titled “Evidence”A proposal names the edges of the graph it rests on, as the read tools returned them. Affectra checks that each one exists in your data when the proposal is filed. An edge that does not exist fails the call with proposal.evidenceUnknown, with the position of the edge. For a conflict, cite the excludedBy edge from explain_finding: it is evidence for a statement on the group’s CVE, and the proposal keeps the edge’s fixed_version.
Node IDs
Section titled “Node IDs”Your organization’s nodes have IDs of the form urn:affectra:<class>:<id>, for example urn:affectra:release:…. Public records keep their own IDs: CVE-2024-1234, GHSA-…, CWE-79. Another organization’s ID answers notFound, the same as one that does not exist.
Prompts
Section titled “Prompts”Prompts are Affectra’s workflows, written for your assistant. You pick one, for example /mcp__affectra__triage_product in Claude Code, and give its arguments. The assistant then follows the steps with the tools above. A prompt adds no access: each tool still checks your role.
| Prompt | What it does | Arguments | Lowest role |
|---|---|---|---|
assess_release |
Assesses a release’s findings against the source code in your repository and proposes VEX statements where the code is clear. | release |
Member |
investigate_vulnerability |
Finds the releases and units a vulnerability reaches, and what you already said about it. | vulnerability |
Viewer |
review_proposals |
Summarizes the pending proposals, their evidence and explanations, for the person who reviews them. | release (optional) |
Viewer |
triage_product |
Ranks a product’s findings and says what to look at first. | product |
Viewer |
Argument values reach the assistant as data, quoted after the workflow. The same workflows are available as Agent Skills: see Use Affectra’s workflows.
Feed status
Section titled “Feed status”Every graph answer has feed_status: for each feed its checked_at, its state (ok, stale or very_stale) and subscribed. subscribed is false for a feed your organization turned off; findings that only that feed reports are hidden from the answer. list_feeds names the feeds and says who turned one off.
Limits
Section titled “Limits”| Calls | Counted against | Default |
|---|---|---|
tools/call of a read tool |
traversal | 60 a minute, bursts of 20 |
tools/call of a propose tool |
write | as for the API |
Budgets are per credential: per API key, or per person for an assistant signed in as that person. Over a budget, a tool call fails with request.rateLimited, with budget and retry_after in seconds. Using the API describes the other budgets.
Errors
Section titled “Errors”A tool that fails answers with isError: true and the API’s error code in structuredContent. The codes you see most:
| Code | Meaning |
|---|---|
notFound |
No such node in your organization. |
graph.vulnerabilityUnknown |
Affectra has no record of the vulnerability ID. |
graph.timeout |
The query took too long. Narrow it. |
request.fieldRequired |
A required argument is missing. |
auth.roleTooLow |
Your role does not allow the tool. |
request.rateLimited |
Over a budget. Wait retry_after seconds. |
proposal.evidenceUnknown |
An evidence edge is not in your data. |
events.cursorInvalid |
list_events got an after that is not one of its cursors, or one older than 30 days. Call it again without after. |
proposal.basisMismatch |
A carry-over names a statement that does not match exactly. |
vex.* |
The proposed statement is not valid, as for a statement recorded through the API. |
Errors of the protocol itself, such as an unknown method or malformed JSON, are JSON-RPC errors.
Text from third parties
Section titled “Text from third parties”Values written by SBOM authors and advisory publishers, such as component names and advisory summaries, are returned in named properties and never mixed into Affectra’s own summaries. The tool descriptions tell the assistant that such values are data, never instructions.