Control tool access

Every MCP server in Catalyst has an access policy — an allow-list that decides which caller App IDs may use which tools. The policy is created automatically with each MCP server and starts deny-all: no caller can discover or call any tool until you grant access. You change it at runtime with the diagrid mcpserver access commands — no redeploy, no code change.

Catalyst enforces the policy at its MCP proxy endpoint, on the hop between the caller and the server:

• Discovery is filtered. tools/list returns only the tools the calling App ID is granted, so an unauthorized tool is invisible rather than merely un-callable.
• Calls are gated. An unauthorized tools/call is rejected with 403 Forbidden before the request reaches the upstream server. With a full deny-all policy the MCP session itself is refused.

Prerequisites

• An MCPServer connection in your project.
• The Diagrid CLI, authenticated with diagrid login.

See the current policy

A new MCP server denies everything. Inspect its policy at any time:

# Full detail for one server
diagrid mcpserver access get mcp-server

# Every server's policy in the project
diagrid mcpserver access list

For a brand-new server, get reports a deny-all policy with no rules.

Grant access to specific tools

Grant a caller App ID access to one or more named tools. A rule is an allow-list entry: it names a caller (an App ID, or * for any) and the tools it may use (names, or * for all).

diagrid mcpserver access grant mcp-server \
  --caller analyst-agent \
  --allow-tools add,echo \
  --wait

analyst-agent can now discover and call add and echo. Any other tool stays hidden in tools/list and returns 403 if called. Every other caller is still denied.

note

A policy change is rolled out to the data plane before it takes effect, which takes a few seconds. Apply one change at a time and pass --wait, or preview a verdict instantly with access test.

Open a server to all callers

To allow every caller every tool — useful for a trusted internal server — use wildcards:

diagrid mcpserver access grant mcp-server --caller "*" --allow-tools "*" --wait

Revoke access

Remove specific tool grants, or a caller's entire rule:

# Remove only the echo grant; analyst-agent keeps add
diagrid mcpserver access revoke mcp-server --caller analyst-agent --allow-tools echo

# Remove the caller's whole rule
diagrid mcpserver access revoke mcp-server --caller analyst-agent --all

Preview a verdict

access test evaluates a hypothetical call locally with the same policy the data plane enforces. It does not call the upstream server and does not wait for a rollout, so it's the fastest way to confirm a rule before your agent runs:

diagrid mcpserver access test mcp-server \
  --caller analyst-agent \
  --tool get_weather_alert
# → ALLOWED: ...   or   DENIED: ...

How the policy is structured

Under the hood, each MCP server has exactly one MCPServerAccessPolicy resource (cra.diagrid.io/v1beta1), named the same as the server and lifecycle-locked to it — Catalyst creates and deletes it with the server, and you edit only its rules through the CLI. You don't author this resource by hand; the structure below is what the access commands manage for you.

apiVersion: cra.diagrid.io/v1beta1
kind: MCPServerAccessPolicy
metadata:
  name: mcp-server          # matches the MCPServer name (1:1)
spec:
  mcpServerRef: mcp-server
  rules:                    # empty ⇒ deny everything
    - callers:
        - appID: analyst-agent   # exact App ID, or "*" for any caller
      grants:
        - capability: tools       # the unit of authorization today
          names: ["add", "echo"]  # tool names, or "*" for all

A call is allowed only if some rule matches both the caller and the tool; otherwise it is denied.

What's next

• Connect an MCP client — point your agent at the server and see the policy take effect.
• Authentication — how callers authenticate to Catalyst and Catalyst to the upstream server.
• Security and trust posture — the identity, authorization, and audit model behind these controls.