MCP Security API

The MCP Security API provides a headless evaluation endpoint for external systems to check MCP tool call payloads against the policy engine and DLP pipeline without a chat session. Use this endpoint to integrate Arbitex policy enforcement into custom agent orchestration frameworks, CI/CD pipelines for prompt testing, or any system that needs to pre-check content before sending it to an MCP server.

For the admin guide covering MCP server registration, policy binding, and tool authorization, see MCP Governance Admin Guide.

Endpoint

Method	Path	Auth	Description
`POST`	`/api/mcp/evaluate`	Bearer (admin)	Evaluate an MCP payload against the policy engine

Authentication

The endpoint requires admin-level API key authentication. Pass the key as a Bearer token:

Authorization: Bearer <admin-api-key>

The org_id in the request body is cross-checked against the authenticated key’s organization. A 403 is returned if they do not match.

Request

`POST /api/mcp/evaluate`

Submit an MCP tool call payload for policy evaluation and DLP scanning.

Content-Type: application/json

Request body

Field	Type	Required	Description
`server_id`	UUID	Yes	ID of the registered MCP server (must exist and be enabled in the org)
`tool_name`	string	Yes	Name of the tool being invoked (max 255 chars)
`payload`	string	Yes	Content to evaluate (the tool call argument or response body)
`direction`	string	Yes	`"input"` (data coming from MCP server) or `"output"` (data going to MCP server)
`org_id`	UUID	Yes	Organization ID (must match the authenticated API key’s org)
`agent_identity`	string	No	Agent identity label for per-agent tool authorization checks (max 255 chars)
`agent_session_id`	UUID	No	Agent audit session ID to link this evaluation to a session timeline
`reasoning`	string	No	Agent’s reasoning for the tool call (max 4096 chars, logged in audit events)

Response

Success (200 OK)

Field	Type	Description
`decision`	string	`"allow"`, `"block"`, or `"redact"`
`findings`	array	DLP findings from the 5-tier pipeline (each finding is an object with detection details)
`policy_rule_matched`	string or null	ID of the policy rule that matched, or `null` if no rule matched

Evaluation order

The endpoint evaluates in this order:

Server validation — confirms server_id exists and is enabled in the org
Agent tool authorization — if agent_identity is provided, checks per-agent tool authorization policies; denied agents return block immediately
Tool allowlist/blocklist — fast pre-gate check against the server’s configured tool lists; blocked tools return immediately
DLP pipeline — runs run_intake_pipeline() (direction=input) or run_output_scan() (direction=output) with full 5-tier scanning and policy engine evaluation

Every evaluation emits an mcp.security_eval audit event regardless of the decision. If agent_session_id is provided, the event is linked to the session timeline.

Rate limiting

The endpoint is subject to per-org rate limiting. When the rate limit is exceeded, the endpoint returns 429 Too Many Requests with a Retry-After header.

Rate limits are configured per organization and follow the same tier structure as other admin API endpoints. Contact your account administrator for specific limits.

Examples

Allow decision

A tool call payload with no sensitive content:

curl -X POST https://your-platform/api/mcp/evaluate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "019577a3-1111-2222-3333-444455556666",
    "tool_name": "search_issues",
    "payload": "Find all open bugs assigned to the backend team",
    "direction": "output",
    "org_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "decision": "allow",
  "findings": [],
  "policy_rule_matched": null
}

Block decision

A tool call response containing PII that matches a policy rule:

curl -X POST https://your-platform/api/mcp/evaluate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "019577a3-2222-3333-4444-555566667777",
    "tool_name": "query_contacts",
    "payload": "Contact: Jane Doe, SSN: 123-45-6789, Phone: 555-0100",
    "direction": "input",
    "org_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "decision": "block",
  "findings": [
    {
      "type": "SSN",
      "confidence": 1.0
    }
  ],
  "policy_rule_matched": "019577a3-rule-uuid-pii-block"
}

Block decision (agent tool authorization)

An agent without permission to call the specified tool:

curl -X POST https://your-platform/api/mcp/evaluate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "019577a3-2222-3333-4444-555566667777",
    "tool_name": "update_account",
    "payload": "{\"account_id\": \"001XX000003GHP\"}",
    "direction": "output",
    "org_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_identity": "read-only-analyst",
    "agent_session_id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
    "reasoning": "Need to update the account notes field"
  }'

{
  "decision": "block",
  "findings": [],
  "policy_rule_matched": null
}

Error codes

Status	Description
`400`	MCP server is disabled, or missing/invalid request fields
`401`	Missing or invalid API key
`403`	`org_id` does not match the authenticated API key’s organization
`404`	MCP server not found for the given `server_id` in the org
`429`	Per-org rate limit exceeded. Check `Retry-After` header.
`500`	Unexpected server error during evaluation

Error response format

{
  "detail": "MCP server not found"
}

CSRF exemption

The /api/mcp/ path is exempt from CSRF header requirements because MCP tool calls originate from programmatic clients, not browser sessions. Authentication is still required via Bearer token. See Security Architecture — CSRF for details.

MCP Governance Admin Guide — server registration, policy binding, tool authorization, troubleshooting
MCP Server Admin API — MCP server CRUD (/api/v1/admin/mcp-servers/)
Agent Session API — agent session auditing and timeline
Policy Engine API — policy rule CRUD and simulation
DLP Architecture — 5-tier scanning pipeline internals