MCP gateway
The MCP gateway enforces a decision in your agent’s production tool path. It sits between the agent and other MCP servers. The agent sends the tool call here. POST /v1/gateway/mcp decides it and, when the decision allows it, forwards it to a registered upstream MCP server.
This is not the Vulnify MCP server. That server is what Cursor, Claude, and VS Code connect to. It gives those assistants tools to check an action, read a decision, and test policies. It does not sit on the path between your agent and another MCP server.
| MCP gateway | Vulnify MCP server | |
|---|---|---|
| Role | Enforce the decision in the agent’s production tool path | Tools for an AI assistant or an IDE |
| Callers | Your agent, on the way to another MCP server | Cursor, Claude, VS Code, or your own code |
| Address | POST /v1/gateway/mcp on https://api.vulnify.io |
https://mcp.vulnify.io/mcp |
POST /v1/gateway/mcp maps the tool name to an action by substring. Vulnify does not execute arguments. The upstream MCP server does, after a decision that allows the call.
The response is the same decision body as POST /v1/events, plus gateway. Unlike the HTTP gateway, this object has no upstream. gateway.upstream is not in the schema. mappedAction is the action the tool name mapped to. allowed is whether that decision allows the call.
The Node.js guardMcpHandler adapter is a different path. It guards a handler inside your own MCP server and calls POST /v1/events. Use that when the server runs in your process. Use this endpoint when the caller sends the tool call to Vulnify.
Request
Section titled “Request”curl -X POST https://api.vulnify.io/v1/gateway/mcp \ -H "Authorization: Bearer $VULNIFY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "routeId": "ROUTE_ID", "tool": "crm.export_contacts", "resource": "Customer Database", "arguments": { "limit": 500 } }'| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key | header | no | string | Retries with the same key (per organization and endpoint, 24 hours) return the stored decision instead of deciding again. The replay always includes finalDecision, derived from the stored decision and the current review. |
| Field | Type | Required | Description |
|---|---|---|---|
agent | string (max length 100) | no | Agent name as registered in Vulnify. |
agentId | string (uuid) | no | Agent id. Use this or `agent`. |
resource | string (max length 100) | no | Resource name as registered in Vulnify. |
resourceId | string (uuid) | no | Resource id. Use this or `resource`. |
destination | INTERNAL | EXTERNAL_EMAIL | EXTERNAL_API | no | |
recordsAffected | integer (0–100000000) | no | |
content | string (max length 100000) | no | Optional text scanned for sensitive data. Scanned in memory and never stored. |
routeId | string (uuid) | no | Registered MCP route (supplies a default agent). |
tool | string (min length 1, max length 200) | yes | MCP tool name. Mapped to an action by substring. |
arguments | object | no | Tool arguments. Not executed by Vulnify. |
tool is required. A registered MCP route supplies a default agent. The 400 response still describes a validation error when agent and resource are not identified. arguments is an object of any keys. It is not executed by Vulnify.
Response
Section titled “Response”Decision: { id, decision, finalDecision, evaluatedDecision, monitored, riskLevel, riskScore, reasons, policy, decisionSource, dlpFindings, lgpdCategories, review, quotaExceeded, sandbox }. decision is the stored outcome and does not change when a review is resolved. finalDecision is the effective outcome (ALLOW after approval, BLOCK after denial or expiry, REVIEW while pending) and is always present, including an idempotent replay. quotaExceeded flags a plan overrun without blocking; sandbox is true for TEST keys.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | |
decision | ALLOW | REVIEW | BLOCK | yes | Decision recorded on the event. It does not change when a review is resolved. |
finalDecision | ALLOW | REVIEW | BLOCK | yes | Effective outcome. Equals `decision` when there is no review. REVIEW while a review is pending. ALLOW after approval, BLOCK after denial or expiry. Always present, including an idempotent replay of a response stored before this field existed: the replay derives it from the stored decision and the current review. |
evaluatedDecision | ALLOW | REVIEW | BLOCK | yes | What full enforcement would have decided. Differs from `decision` in monitor mode. |
monitored | boolean | yes | |
riskLevel | LOW | MEDIUM | HIGH | CRITICAL | yes | |
riskScore | integer (0–100) | yes | |
reasons | array of string | yes | |
policy | object or null | yes | Top matched policy. Informational: it did not necessarily set the decision, see `decisionSource`. |
policy.id | string (uuid) | yes | |
policy.name | string | yes | |
decisionSource | engine | policy | no | 'policy' when the matched policy set `evaluatedDecision`. 'engine' when the Risk Engine or the permission check set it, including when engine risk is stricter than the matched policy (then `reasons` has e.g. "Engine risk CRITICAL overrides policy REVIEW"). Absent on an idempotent replay of a response stored before this field existed. |
dlpFindings | array of string | yes | Sensitive-data types found in `content`. |
lgpdCategories | array of IDENTIFICATION | CONTACT | LOCATION | FINANCIAL | HEALTH | COMPANY | CREDENTIALS | yes | LGPD categories derived from `dlpFindings`. |
review | object or null | yes | Null when the event has no human review. |
review.status | PENDING | APPROVED | DENIED | EXPIRED | yes | |
review.expiresAt | string or null (date-time) | yes | |
review.decidedAt | string or null (date-time) | yes | |
review.note | string or null | yes | |
quotaExceeded | boolean | yes | Plan quota is over the limit. The decision is still made. |
sandbox | boolean | yes | True when the event was created with a TEST key. |
gateway | object | no | |
gateway.protocol | MCP | yes | |
gateway.routeId | string or null (uuid) | no | |
gateway.tool | string | yes | |
gateway.mappedAction | READ_DATA | WRITE_DATA | DELETE_DATA | EXPORT_DATA | SEND_EMAIL | yes | |
gateway.allowed | boolean | yes |
| Header | Description |
|---|---|
X-Request-Id | Request id for support and log correlation (a caller-sent plain id is kept). |
x-api-version | Machine API contract (v1). |
x-vulnify-version | API build (SemVer, see /changelog). |
Idempotent-Replay | "true" when the body is a stored replay |
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
400 | Validation error (agent/agentId and resource/resourceId are required) |
401 | Missing, invalid, revoked or expired API key |
403 | Key bound to another agent, or caller IP not in the key allowlist |
404 | Unknown agent, resource or gateway route |
413 | JSON body larger than 200 KB |
429 | Rate limit exceeded |
A 413 means the JSON body is larger than 200 KB. It is a client error, including when a caller hoped to fail open. See Errors.
The call is listed in the gateway call log with protocol MCP.

