Skip to content

MCP endpoint in the named organization, for user tokens and its API keys

POST
/v1/orgs/{org}/mcp
curl --request POST \
--url https://example.com/v1/orgs/example/mcp \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "jsonrpc": "2.0", "id": "example", "method": "initialize", "params": {} }'

The graph as Model Context Protocol tools, and agent proposals for a person to decide (propose_vex, propose_cpe_mapping, propose_unit_release_link, get_proposal and list_proposals, members only for the first three), over stateless Streamable HTTP (protocol version 2026-07-28). One JSON-RPC 2.0 request per POST, answered with one application/json response; no sessions, no server-sent events, no batches. Each request names the version and the client capabilities in params._meta and sends MCP-Protocol-Version, Mcp-Method and (tools/call) Mcp-Name; a missing or different header answers 400 with JSON-RPC error -32020, an unsupported version 400 with -32022 and the supported versions in data. Methods: server/discover, tools/list, tools/call, prompts/list and prompts/get (the workflows assess_release, investigate_vulnerability, triage_product and review_proposals, filtered by role); any other answers 404 with -32601. A request without that _meta is served as protocol 2025-11-25 or 2025-06-18, with initialize and ping as well. Notifications get 202. A request with an Origin header the deployment doesn’t allow answers 403. A user token acts with the user’s role in the organization; another organization’s key answers 404. Bearer credentials only: the session cookie answers 401.

OAuth for MCP, where the deployment turns it on: this route, and no other, also takes access tokens of the customer realm issued to an assistant client. A token must name the API’s MCP audience (the API’s public URL plus /v1/mcp) and an assistant client as azp; it acts as the signed-in user (matched by the login web sign-in linked; a login that never signed in to Affectra is refused) with their role in the organization in the path, and a user who isn’t a member gets 404. A 401 carries WWW-Authenticate Bearer resource_metadata=“”, scope=“openid affectra-mcp” (and error=“invalid_token” for a refused credential), so MCP clients find the authorization server. tools/call is charged to the traversal budget (propose_vex, propose_cpe_mapping and propose_unit_release_link to write, as POST /v1/orgs/{org}/proposals) and a refusal is a tool error request.rateLimited with params budget and retry_after; the other methods are charged to read. Tool errors (isError true) carry the problem codes of the graph and proposal routes in structuredContent (code, params, detail). Requests up to 64 KiB.

org
required
string

Organization (tenant) slug, e.g. alpenrobotik

Media typeapplication/json
object
jsonrpc
required
string
Allowed values: 2.0
id

Absent for a notification

string | integer | null
method
required
string
params
object
key
additional properties
any

The JSON-RPC response, a result or a JSON-RPC error

Media typeapplication/json
object
jsonrpc
required
string
Allowed values: 2.0
id
required
string | integer | null
result

For tools/call: content (one text block composed from our own fields), structuredContent (the graph envelope, GraphResponse) and isError.

object
key
additional properties
any
error
object
code
required

-32700 parse, -32600 invalid request, -32601 unknown method, -32602 invalid params or unknown tool, -32603 internal

integer
message
required
string

Example

{
"jsonrpc": "2.0"
}

A notification was received; no body

Not a JSON-RPC request, a batch, a missing or mismatched MCP header (-32020), missing _meta fields (-32602) or an unsupported protocol version (-32022); a JSON-RPC error body

Missing or invalid bearer credential or OAuth access token, or the session cookie; WWW-Authenticate points to the protected-resource metadata when OAuth for MCP is on

An Origin header the deployment doesn’t allow (a JSON-RPC error body)

Another organization’s or no organization (problem details), or, for a 2026-07-28 request, a JSON-RPC method the server doesn’t have (a JSON-RPC error -32601 body)

Any method but POST (GET has no stream to open)

Request body over 64 KiB (a JSON-RPC parse error body)

Over the operation’s rate-limit budget (x-affectra-budget): code request.rateLimited with params.budget. Wait Retry-After seconds before trying again.

Media typeapplication/problem+json

Every error answer, Content-Type application/problem+json. The web app and integrations translate code; detail is English, for people reading curl output or CI logs, and may change wording at any time. Match on code, never on detail.

object
status
required

The HTTP status

integer
code
required

Stable error codes. A code is never renamed; new ones may be added, so a client falls back to detail for a code it doesn’t know. Another organization’s object answers notFound, the same as a missing one.

string
Allowed values: notFound internal request.invalidJson request.invalid request.alreadyExists request.timeInvalid auth.required auth.csrfMissing email.invalid accounts.passwordUnavailable locale.invalid request.rateLimited auth.sessionRequired auth.roleTooLow auth.githubTokenUploadOnly org.suspended org.required request.fieldRequired request.textInvalid request.timeout server.notReady catalog.unavailable report.invalid report.wrongTenant settings.csafNamespaceInvalid settings.digestHourInvalid settings.timeZoneInvalid sbom.invalid sbom.limitExceeded sbom.signatureInvalid sbom.signatureRequired sbom.signatureUnavailable upload.hardwareRevisionRenamed upload.malformed upload.unexpectedPart upload.sbomMissing upload.tooLarge upload.unreadable provenance.invalid provenance.sbomAttestation provenance.signatureRequired provenance.unavailable vex.vulnerabilityInvalid vex.statusInvalid vex.justificationUnknown vex.justificationNotAllowed vex.justificationRequired vex.actionRequired vex.statementTooLong vex.csafNamespaceRequired vex.csafNoStatements release.hasVexStatements finding.refInvalid mapping.purlInvalid mapping.purlVersioned mapping.purlCoveredByOsv mapping.cpeFieldInvalid mapping.builtIn mapping.csafProviderUnknown mapping.csafKindInvalid mapping.csafValueInvalid feeds.notSubscribable accounts.setupEmailLimit member.exists member.joined member.roleInvalid member.ownerGrantDenied member.ownerChangeDenied member.ownerRemoveDenied member.lastOwner github.orgInvalid github.teamInvalid github.roleInvalid github.adminRequired key.nameInvalid key.roleInvalid key.purposeInvalid product.keyInvalid product.keyExists product.keyLocked product.supportEndsInvalid alias.reportedInvalid alias.exists publisher.repositoryInvalid publisher.fieldTooLong publisher.idsIncomplete publisher.repositoryNotFound publisher.githubUnreachable publisher.workflowInvalid publisher.refPatternPrefix publisher.refPatternInvalid publisher.exists graph.vulnerabilityUnknown graph.timeout proposal.evidenceUnknown proposal.evidenceTooLarge proposal.kindInvalid proposal.basisInvalid proposal.notCarryOver proposal.basisMismatch proposal.notPending proposal.sourceSuperseded proposal.ownProposal proposal.fourEyes proposal.personRequired proposal.batchTooLarge proposal.vulnerabilityChanged proposal.reportedChanged proposal.releaseUnknown proposal.evidenceMissing notifications.unavailable notifications.findingsInvalid notifications.tokenInvalid webhook.urlRejected webhook.limitReached webhook.formatUnavailable webhook.headerInvalid webhook.eventTypesInvalid webhook.disabled events.cursorInvalid
detail
required

What went wrong

string
params
required

Values the code’s message needs, e.g. {“field”: “version”}. Only values the caller sent or may see. Empty when the message needs none.

object
key
additional properties
any

Example

{
"code": "notFound"
}
Retry-After
integer
>= 1

Seconds until a request would be allowed again, at least 1