Skip to content

Manage agent policies and enforcement modes by API

The MCP gateway decides every agent tool call with intent policies and applies them in a server’s mode: shadow logs what it would deny, enforce denies it. The console’s Intent Policies and MCP Gateway pages manage both. This API does the same from a script or a GitOps pipeline, with the same checks and the same audit records.

Before you start

Create an API key with the scopes you need. The key acts as the person who created it, and that person needs the same permission in the console, checked on every call:

Scope Lets the key The key’s owner needs
read:agent_policies list, read and simulate intent policies to see intent policies (and simulate them)
write:agent_policies create and change intent policies to manage intent policies
read:mcp_servers list servers, read their modes, preview a promotion to see the MCP gateway’s tool bindings
write:mcp_servers switch a server between shadow and enforce to manage MCP servers

The write scopes are high impact: a key that has them waits for approval before it is issued. A key can’t also hold mcp:authorize, so the gateway that enforces policy can’t rewrite it or switch it off. Writes also need the owner to be an active person: a suspended or departed owner’s key stops working.

Write a policy, test it, then turn it on

Create the policy as a draft. Drafts are stored but not evaluated.

Terminal window
curl -X POST https://app.atmanid.com/api/v1/agent-policies \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"name": "Hold pushes to main", "intent_pattern": "github:push", "resource_pattern": "*/main",
"action": "REQUIRE_HITL", "priority": 20}'

Test what the active policies would decide for one call. Nothing is written:

Terminal window
curl -X POST https://app.atmanid.com/api/v1/agent-policies/simulate \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"agent_id": "agt-release-bot", "intent": "github:push", "resource": "acme/web/main"}'

The answer gives decision (what the policies say), enforced_decision (what the gateway would return right now, counting an active just-in-time session), and a trace of every policy and why it matched or not. The simulator reads ACTIVE policies only, so a draft shows up in it once you activate it.

When you’re ready, activate the policy:

Terminal window
curl -X PATCH https://app.atmanid.com/api/v1/agent-policies/aip-mh3k2x9 \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"status": "ACTIVE"}'

A PATCH changes only the fields you send; "status": "ARCHIVED" retires a policy. A second policy with the same name is refused with 409 CONFLICT. Every change is recorded (AGENT_POLICY_CREATED, AGENT_POLICY_UPDATED) with the key’s owner and the API key’s id.

GET /api/v1/agent-policies lists policies 25 per page (up to 100) with the usual data, total, page, limit and total_pages. Filter with agent_id (the agent’s own policies and the global ones, as the gateway reads them), status and action (a value outside the listed ones is 400 INVALID_PARAM); sort with sort_by (priority, name, created_at, updated_at) and sort_dir.

Move a server from shadow to enforce

New servers start in shadow. First see what enforce would deny:

Terminal window
curl https://app.atmanid.com/api/v1/mcp/servers/mcp-github/mode-preview -H "Authorization: Bearer $ATMANID_KEY"

The preview covers the last 7 days. For the gateway mode it counts the calls it would deny (would_deny_*) by reason: tool scope, the two rate limits, and payload inspection. For intent policy it gives the same counts, plus coverage: tools agents may call that no intent binding covers. Enforce denies those even if nobody called them during the week. If the would-deny counts are calls you meant to allow, fix the grants or policies first.

Then switch:

Terminal window
curl -X PATCH https://app.atmanid.com/api/v1/mcp/servers/mcp-github/mode \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"gateway_mode": "ENFORCE", "intent_mode": "ENFORCE"}'

gateway_mode takes SHADOW or ENFORCE; intent_mode takes OFF, SHADOW or ENFORCE. Direct mode, which skips the gateway’s checks, can’t be set by API. Both modes change together or not at all, and changed lists what this call moved. Every call is recorded, even one that sets a mode it already has, as a save in the console is: AGENT_MCP_GATEWAY_MODE_UPDATED or AGENT_MCP_INTENT_MODE_UPDATED with the before and after values and the API key’s id. Moving into enforce also sets gateway_promoted_at. A call is safe to repeat.

GET /api/v1/mcp/servers lists servers with their modes. Filter with gateway_mode, intent_mode or governance_status. Upstream URLs, credentials and launch commands are never returned, and a locally discovered server’s description is masked as in the console.

The full request and response schemas are in the API reference.

© AtmanID · Privacy