Tag-Based Read-Only Mode
Relevant source files
The following files were used as context for generating this wiki page:
Tag-Based Read-Only Mode provides a security mechanism to restrict AI agents to infrastructure querying without allowing state modifications. The system enforces this by completely hiding write-capable tools from the Model Context Protocol (MCP) client during discovery and blocking direct execution attempts. This feature targets security-conscious environments where read-only access is a prerequisite for deploying AI assistants.
Sources: dev/adr/0004-tag-based-read-only-mode.md:7-12, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:65-69
Defense-in-Depth Architecture
The server implements three layers of protection to ensure write operations remain blocked even if discovery layers are bypassed. The architecture relies on FastMCP's tagging system to identify restricted tools.
| Layer | Component | Behavior in Read-Only Mode |
|---|---|---|
| Discovery | on_list_tools() | Filters out all tools tagged with "write". |
| Execution | on_call_tool() | Rejects direct invocation of tagged tools by name. |
| Surface | Startup Mounting | Does not mount write sub-applications at the ASGI level. |
| Fallback | Allowlist | Permits only known-safe tools if tag resolution fails. |
Sources: dev/adr/0004-tag-based-read-only-mode.md:19-30, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:129-132
Tool Discovery and Hiding
When read_only=true, the server uses the ReadOnlyMiddleware to invoke FastMCP's restrict_tag() function. This ensures that an AI agent cannot discover write tools like node_upsert or mutate_graphql because they do not appear in the tool listing. This prevents "hallucinated" tool calls based on the agent's training data.
Sources: dev/adr/0004-tag-based-read-only-mode.md:19-23, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:75-78
Fail-Closed Execution Policy
If an agent attempts to invoke a write tool by name, the server blocks the request at the middleware layer. To ensure safety, a fail-closed allowlist permits only specific tools if the system cannot verify a tool's tags.
This diagram illustrates the logical flow of tool execution validation when Read-Only mode is active.
Sources: dev/adr/0004-tag-based-read-only-mode.md:24-30, dev/constitution.md:46-48
Configuration and Tool Tagging
Read-Only mode is controlled via global server configuration and individual tool metadata. Developers must explicitly tag new tools to include them in or exclude them from the read-only filter.
Configuration Variables
The server uses ServerConfig to manage the read-only state. These values are typically loaded from environment variables.
| Variable | Type | Default | Description |
|---|---|---|---|
INFRAHUB_MCP_READ_ONLY | boolean | false | When true, restricts server to read-only operations. |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:65-66, GPT.md:38-39
Write Tool Tagging Requirements
All tools that perform create, update, or delete operations MUST be tagged with "write". This tag is used both by ReadOnlyMiddleware for security and AuthMiddleware for OIDC scope enforcement.
Restricted Write Tools include:
node_upsertnode_deletepropose_changesmutate_graphql
Sources: dev/adr/0004-tag-based-read-only-mode.md:14-16, dev/constitution.md:46-48, GPT.md:94-95
Default Safe Tools (Allowlist)
The fallback allowlist permits the following tools even if the tagging context is unavailable:
get_schemaquery_graphqlget_nodessearch_nodes
Sources: dev/adr/0004-tag-based-read-only-mode.md:27-30
Implementation Constraints
The Read-Only mode is implemented with a strict "Branch-Safe" philosophy. The ReadOnlyMiddleware acts as the primary gatekeeper, but other principles reinforce the read-only behavior.
- Protocol Compliance: Error responses for blocked tools must use MCP-standard error codes and must not leak internal backend details.
- Startup Validation: Configuration is validated via
pydantic-settingsat startup; if OIDC or auth settings conflict with read-only requirements, the server fails fast. - Application Lifecycle: In read-only mode, write-capable sub-applications are not mounted to the main server, effectively removing the code paths from the runtime memory.
Sources: dev/constitution.md:15-17, dev/adr/0004-tag-based-read-only-mode.md:31-33, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:82-84
Summary
Tag-Based Read-Only Mode is a core security feature of the Infrahub MCP server that uses defense-in-depth to protect infrastructure state. By combining discovery-layer filtering, execution-layer blocking, and application-layer mounting restrictions, the system ensures that AI agents can only query data when configured for safety. The reliance on the "write" tag allows the security model to scale automatically as new tools are added to the platform.