Skip to content

Agent Mesh

docs: the service is the unit of authorization, and say so where it matters

Antonio Ojea1283046dedb0
diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.md
index b9cf8692..e8d71043 100644
--- a/site/content/docs/development/policy.md
+++ b/site/content/docs/development/policy.md
@@ -81,6 +81,7 @@ Admins manage central permissions dynamically via the Control Plane REST API. Th
* **Strict Namespaces**: There are no implicit fallbacks. `system://...` is used for internal services, `mcp://...` for node services, `inference://...` for AI models, etc. Service names must be valid domain labels (e.g. `value1.value2.value3`).
* **Wildcards**: SAM natively supports domain-level wildcards to build complex policies. The control plane generates specific facts like `granted_service_exact($type, $name)`, `granted_service_prefix($type, $prefix)`, `granted_service_suffix($type, $suffix)`, `granted_service_all_in_type($type)`, or `granted_service_all_types()`. You can grant access to an entire type via `mcp://*`, allow prefix-based wildcard matching like `mcp://*.service.local` (which matches services ending in `.service.local`), suffix-based wildcard matching like `mcp://service.*` (which matches services starting with `service.`), or global access to everything via `*`.
* **MCP Namespace Convention**: The `mcp://` prefix (`api.MCPServicePrefix`) is the explicit convention for all Model Context Protocol targets.
+ * **The service is the unit of authorization — deliberately.** Mesh policy does not filter individual MCP tools inside a service. The mesh authorizes *names* (see the architecture's "a mesh name is the service namespace" decision), and a registered service is the operator's exposure decision: registering it offers its whole tool surface, exactly as the backend defines it. To offer different privilege tiers, split them into services — register a read-only backend as `mcp://db-reader` and a mutating one as `mcp://db-writer` (see the node configuration example in §6.2) and grant them to different roles. If a third-party MCP server bundles tools you do not want to offer, front it with a backend that exposes only the tools you mean to publish; curating the tool surface is the server registration's job, not the token's.
* **Bindings**: Map OIDC identities (sub/user, email, group) to specific Roles.
### 2.1 Updating Mesh Policy
diff --git a/site/content/docs/user/control-plane-configuration.md b/site/content/docs/user/control-plane-configuration.md
index 1603e609..e103c2c1 100644
--- a/site/content/docs/user/control-plane-configuration.md
+++ b/site/content/docs/user/control-plane-configuration.md
@@ -55,7 +55,7 @@ The Control Plane dynamically issues permissions inside the Biscuit token based
The policy defines what endpoints and services agents are permitted to use:
* **`allowed_targets`**: Restricts which logical endpoints the agent can route connections to. Use resolved Biscuit facts: `group:<name>`, `user:<sub-id>`, `email:<email>`, `role:<role-name>`, or `node:<peer-id>`.
-* **`allowed_services`**: Restricts the application-level services the agent can invoke. Services are prefixed by their protocol type and URI scheme (e.g., `mcp://local-shell-tools` or `inference://openrouter`). Wildcards are supported (e.g., `mcp://*`).
+* **`allowed_services`**: Restricts the application-level services the agent can invoke. Services are prefixed by their protocol type and URI scheme (e.g., `mcp://local-shell-tools` or `inference://openrouter`). Wildcards are supported (e.g., `mcp://*`). The service is deliberately the unit of authorization: a grant offers the service's whole tool surface, so publish different privilege tiers as different services (e.g. `mcp://db-reader` vs `mcp://db-writer`) rather than expecting the mesh to filter tools inside one backend.
* **`allowed_agents`**: The agent namespaces a node with this role can use. When a node forwards a request for a sandboxed agent, it sends the agent's name with it. The receiving node accepts that name only if it falls inside one of these namespaces. A node with no `allowed_agents` grant cannot name any agent. Accepted patterns are `*.prod.acme.example`, `acme.*`, an exact ID such as `reviewer-7.prod.acme.example`, or `*` for any agent.
* **`allowed_labels`**: The labels a node with this role may declare when it enrolls, as `*`, `key=*` or `key=value`. A node sends its own labels in its enrollment request, so this is what decides which of them the control plane is willing to sign into `label()` facts. A role granting none means a node holding it can declare none. Peers gate on those facts with `required_labels`, so a node that could declare anything could satisfy any such requirement.