MCP Security

Principal authorization#

Authorization is independent of tool publish state. Two principal kinds may be granted allow or deny policies:

Actions are read (discover) and invoke (call a tool). There is deliberately no manage tool action: mutating the catalog and policies is a management-surface capability (mcp:manage), not a principal-grantable action, so it never appears in the access-rule editor.

Adjudication rules#

1. Collect matches. Gather policies matching this principal kind and reference, the requested action, and overlapping resources, ordered by priority (highest first).
2. Deny overrides. If any matched policy denies, deny immediately regardless of priority.
3. Allow on match. Otherwise, if at least one allow matches, allow, narrowed to the requested resources.
4. Default deny. Anything else denies.

Narrowing only#

A request may never widen what an allow grants. If the caller names a server or tool that no allow policy covers, the request is rejected even though some other resource was allowed. A policy with serverIds: null or toolNames: null means "all" within scope; an explicit array narrows it.

Deny reasons surface as no_matching_policy (default deny), explicit_deny (a deny matched), or request_outside_allow (the request tried to widen).

Hosted tools are pre-approved#

The five shipped hosted tools (web_search and the trace and Finding readers) carry a default-allow flag. When adjudication reaches default-deny, those tools are still listed and invocable by an mcp:invoke caller; they need no policy of their own. A matched explicit deny still blocks them, and federation tools stay fully default-deny until an allow policy admits them.

Hosted tools act as the project identity: there is no upstream, no sealed secret, and no credential entry. The only key a caller supplies is the project API key used when connecting an agent; it authenticates ingress and is never an upstream credential.

Upstream authentication posture#

Each federation server carries a persisted authentication posture written by the connection probe and credential lifecycle. Reachability, per-credential enabled state, and this posture are orthogonal facts the call path combines; posture is not recomputed from the credential list at read time.

A connection that is reachable but not callable (missing, invalid, or revoked) still renders and remains fully manageable: edit, discover, sync, publish, and add, test, pause, resume, or promote credentials. Its tools simply cannot be invoked until an active primary exists.

Two upstream failures stay distinct: a 401 means the credential itself is bad (test and promote a fresh secret); a 403 means an upstream authorization decision, treated as a policy or capability problem rather than a bad credential. A 403, network error, or unsupported probe classification is diagnostics-only and does not overwrite the persisted posture; only a successful probe or a 401 probe does.

Upstream error codes on tool calls#

Upstream HTTP status maps to a JSON-RPC code and differs slightly by transport:

The full reserved range is -32000 session expired, -32001 permission denied, -32002 rate limited, -32003 upstream failure, -32004 gateway paused, -32601 method not found, and -32603 internal error. On the HTTP ingress, a paused project gateway returns 503 MCP_PAUSED before the JSON-RPC body; -32004 appears on bypass paths such as the Workbench playground.

Route-level gating#

An API key needs mcp:manage for both management reads and writes; there is no separate read capability. Both mcp:manage and mcp:invoke are absent from the default key capability set, so they are default-deny until granted explicitly. The streamable-HTTP tool gateway accepts only a project API key; a session or any other actor receives 401 UNAUTHORIZED, and a principal the project cannot place receives 403 FORBIDDEN.

Policy and catalog revisions#

At initialize, the allowed set is resolved together with the current policy and catalog revisions. Any change to access policies advances the policy revision; any publish or sync advances the catalog revision. Authorization is re-adjudicated on every exchange, so a policy or catalog change takes effect immediately rather than waiting for a long-lived session to expire. A cached session snapshot is invalidated when its revision no longer matches.

Sealed credentials, not pass-through#

• Upstream secrets are sealed at rest and unsealed only on the outbound call path.
• Listing credentials returns only the id, server id, label, kind, outbound auth method, role (primary or backup), enabled state, last-verified time, and timestamps — never the secret. Exactly one credential is the active primary; every other credential is a backup held for cutover. There is no numeric selection priority.
• The inbound Bearer token presented by the caller is never forwarded upstream. The only outbound auth channel is the sealed upstream secret, injected under the whitelisted outbound auth method: Authorization: Bearer <secret> or X-Api-Key: <secret>. Caller-supplied header names are not accepted.
• The secret never appears in spans, logs, error messages, or returned bodies.

Guardrail scans on every call#

A deterministic, transport-neutral guardrail runs before and after each federated call and never mutates the payload:

• Input: arguments must be JSON-serializable and within 64 KiB.
• No smuggled credentials: arguments cannot contain credential-shaped keys such as authorization, proxy-authorization, cookie, set-cookie, password, secret, token, api-key, or private-key, matched case-insensitively. A hit fails closed; the sealed outbound credential remains the only auth channel.
• Output: tool output must be JSON-serializable and within 256 KiB. Over budget, the output is withheld and replaced with an error.

Fail-closed on purpose: a false positive that denies a benign call is recoverable by the caller; silently forwarding a leaked secret to an upstream is not.

Rate limiting and concurrency#

The bucket dimension differs by runtime, and both runtimes return JSON-RPC -32002 when exceeded:

• Self-hosted Node federation: a fixed-window limiter per (server, tool) at 120 calls per minute, plus a concurrency limit of four in-flight calls per server. These gates live in one process and are not distributed across instances.
• Self-hosted Node hosted tools: a separate per-process limiter per (project, principal, tool) at 60 calls per minute.
• Hosted edge: one fixed-window bucket per (project, principal, tool) at 120 calls per minute, shared across the project's requests; hosted and federation calls share the same bucket.

Upstream 429 responses are surfaced independently of these local limiters.

Transport hardening#

Every outbound target — a native MCP HTTP server and an OpenAPI-federated REST call — must point at a permitted public host:

• The upstream URL must use http or https and carry no embedded credentials.
• Blocked hostnames include localhost, *.localhost, internal, *.internal, local, *.local, metadata, *.metadata, and metadata.google.internal.
• Blocked address ranges include loopback and link-local, RFC 1918 private ranges, CGNAT, documentation and benchmark blocks, and multicast or reserved ranges (IPv4 and the IPv6 ULA, link-local, multicast, and documentation prefixes).
• DNS resolution is re-checked: every resolved address must be public, which blocks DNS rebinding to an internal address.
• Redirects are not followed; the response body is bounded to 1 MB and the call to 30 seconds.

Audit telemetry#

Each outbound federated call produces a bounded client span named MCP <method>. It carries only non-sensitive attributes:

• mcp.method, mcp.tool.name, mcp.server.id, mcp.server.sourceKind
• mcp.principal.kind, mcp.principal.ref, mcp.project.id
• mcp.policy.version, mcp.catalog.version
• mcp.outcome, mcp.rpcResponseStatusCode

Tool arguments, content bodies, upstream URLs, and secrets are never attached. Outcome categories are ok, capability_unavailable, permission_denied, session_expired, rate_limited, upstream_error, and internal.