Description
Scope-Filtered Advertisement makes the MCP catalog honestly reflect what a connection can use instead of exposing a misleading universal menu. createScopedMcpServer resolves effective atoms through /auth/me; registration checks each tool's required atom, while batch gates its members. A failed scope read yields an empty grant set, and read-only mode removes write tools even when the credential holds their permissions.
The workflow is designed for MCP administrators and host integrators. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.
Selling Points
- Reduces agent errors by hiding tools that the credential cannot use.
- Fails closed when authentication or authority resolution is unavailable.
- Supports safer exploration sessions through an explicit read-only switch.
- Preserves route-level authorization beneath advertisement filtering.
- Applies the same policy to local stdio and network HTTP connections.
User Story
An administrator issues a narrowly scoped token and connects an agent in read-only mode. The host lists only permitted read tools and Superpowers; a broken authority lookup exposes only batch, whose members still fail their individual checks. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.
Extension Surface
The feature is configurable: packages/mcp/src/scope.ts defines the atom map and packages/mcp/src/server.ts consumes injected readOnly and grants. Operators select credentials and mode, but cannot replace the policy engine. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.
Capabilities & Limits
- Capability: Credential-derived tool advertisement by access atom.
- Capability: Fail-closed scope resolution with no full-catalog fallback.
- Capability: Server-level read-only suppression plus per-member batch enforcement.
- Limit: Advertisement is an ergonomic security layer, not the sole enforcement point; callers still depend on correct company scoping and route guards.
The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.
Implementation Map
packages/mcp/src/scope.tspackages/mcp/src/server.tsdocs/mcp/scope-and-registration.md