MCP policy templates
Operators can save reusable restrictions and bind them to an entire Project group, one repository, or one session. The controller stores templates, bindings and quota counters in its SQLite database. TUI and web use the same editor and API. There is no per-client policy database.
Managed MCP brokers enforce the allowed methods, tools and request rates. Approval rules can describe permitted work, but cannot widen a template or grant access to credentials, folders or services on their own. Policies use the same controller identity as server users and shared subscriptions; the UI does not authorize access independently. See approval delivery and feature limits.
Configure and apply
Open MCP Policies. Create a template, choose the MCP server ID (* matches all granted servers), enter allowed/denied tool names and optional protocol methods, then set calls per window. Apply the template to a Project group, repository or session. For a standalone repository without a group, use Repository scope. Applied policies lists bindings; d removes the selected binding. Editing a template changes all its existing bindings.
When starting an agent session, an optional checklist appears if templates exist. Continue without additional policies is selected by default; Project/repository restrictions still inherit. Select extra templates with Space/Enter, then choose Continue.
The session creation API accepts mcpPolicyTemplateIds: ["research-readonly"]. Existing repository/Project policies are inherited automatically. A session-specific template adds restrictions; it cannot override the inherited restrictions. Existing sessions pick up changes on their next MCP call or tool discovery without restarting the session or container. An already admitted, running call is not cancelled retroactively.
The JSON API and CLI also support multiple rate limits, including per-tool limits:
{
"id": "research-readonly",
"name": "Read-only research",
"serverId": "research",
"allowedTools": ["search", "read_document"],
"deniedTools": ["delete_document"],
"allowedMethods": null,
"deniedMethods": ["resources/subscribe"],
"rateLimits": [
{ "tool": null, "maxCalls": 30, "windowSeconds": 60, "counterScope": "session" },
{ "tool": "search", "maxCalls": 100, "windowSeconds": 3600, "counterScope": "binding" }
]
}
./devctl mcp policy put research-readonly.json
./devctl mcp policy list
Binding JSON:
{"id":"repo-research","templateId":"research-readonly","scope":"repository","scopeId":"my-repository-id"}
./devctl mcp policy bind repo-research.json
./devctl mcp policy unbind repo-research
./devctl mcp policy delete research-readonly
Operator MCP already exposes run_devctl; use these exact argv through that tool to manage policies. Session MCP credentials cannot create/change/delete templates or bindings. Agents can request a permission through the existing approvals mechanism; they cannot relax their own template.
Tools versus protocol methods
Lists use exact names, not wildcard/prefix matching.
allowedTools and deniedTools refer to MCP tool names, for example search or request_permission. null allowed list means inherit the existing grant; an empty list blocks every tool. Denial wins.
allowedMethods and deniedMethods refer to JSON-RPC protocol methods such as tools/call, resources/read, prompts/get or resources/subscribe. They do not mean HTTP verbs. Leave the allowed methods list null unless an explicit protocol allowlist is needed. An explicit allowlist also needs initialization/notifications and discovery methods required by that MCP client; blocking them can prevent the connection from initializing.
Precedence and rate accounting
All matching Project group, repository and session templates intersect. Group IDs and repository IDs are distinct scope types; an ungrouped repository never inherits a group policy merely because their IDs happen to match. Existing Agent Pack/session allowedTools remains an upper bound. Templates do not grant an MCP server, credential or tool that the session did not already have.
Each limit is an exact sliding window. Up to maxCalls admitted tools/call requests can start in any windowSeconds interval. A session counter is private to the session. A binding counter is shared by sessions matching that binding, separately per MCP server. A per-tool rule counts only that exact tool; a null tool counts all calls.
All applicable limits are checked atomically before any quota is consumed. Denied tools, rejected methods and rate-rejected calls consume no quota. Admitted calls consume quota even if the upstream tool subsequently fails. Discovery and initialization consume no call quota. Queuing is deliberately avoided: a rate rejection returns a retry delay instead of silently waiting or executing later.
Counters survive controller restart. Ordinary edits to a template do not reset unchanged counter positions. Editing/reordering its limit list changes those positions; use a stable list for long-running budgets. Removing a binding explicitly removes its restriction, and reapplying the same binding ID retains unexpired counters. Unused counters expire and are reclaimed. Deleting a repository/session removes its target bindings; reusable templates remain available.
Enforcement and boundaries
Install the updated controller first, then update every participating host-agent before enabling these restrictions. An older host broker enforces only its launch allowlist and cannot enforce the new external-MCP or host-local Run call quotas. Updating only the TUI does not enable enforcement. After the updated components are installed, changing/applying templates requires no session or Project restart.
Builtin devctl calls are checked at their authenticated controller execution endpoint. Host-local durable Run tools are checked by the host MCP broker before execution. Managed external stdio and HTTP MCP servers are checked by the same broker before a message is forwarded. Tool discovery is filtered against the live policy as well as the frozen launch allowlist. JSON-RPC batches are rejected to avoid bypassing per-call admission.
HTTP execution returns 403 for a denied tool and 429 plus Retry-After for a call rate limit. Managed tool responses use isError: true and structuredContent.code (-32003 denied, -32029 rate limited); rate errors include retryAfterMs. Denied protocol methods return a JSON-RPC error. The broker fails closed if the controller cannot be reached; reconnect and retry. Each controller lookup is bounded to two seconds.
Admission transmits only server, protocol method and tool names. It never sends tool arguments/results or upstream credentials to the policy subsystem. Templates accept no secret fields. The host uses the session-scoped identity and cannot choose an arbitrary session in the admission body.
These limits cover MCP transports managed by devctl, not arbitrary API calls made by an agent shell or manually added unmanaged MCP servers. Service gateway HTTP/SQL policies remain separate. This feature does not turn instructions in Markdown into HTTP/SQL enforcement or inspect the semantic contents of tool arguments.
Single-operator controllers use the operator owner namespace. In server-user mode templates, bindings and counters use the authenticated controller principal, and session MCP derives the owner from the session. Clients cannot choose an owner ID. This feature uses the existing server identity system and never permits cross-user container sharing. A shared same-owner container requires identical effective MCP policies for its retained sessions; use a separate container for differing restrictions. Server users.