Transport Modes
Relevant source files
The following files were used as context for generating this wiki page:
Transport Modes define the communication channels between AI assistants and the Infrahub MCP server. The server supports multiple protocols to accommodate different deployment environments, ranging from local developer CLI tools to production-grade web services.
The system primary supports two external transport protocols: Streamable HTTP and Standard Input/Output (stdio). Additionally, an internal In-Memory transport exists for integration testing purposes. The entry point of the application determines the active transport, with uvicorn typically serving HTTP requests and direct script invocation handling stdio.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:275-279, specs/001-infrahub-testcontainers/research.md:38-40
Supported Transport Protocols
The Infrahub MCP server differentiates functionality based on the transport mode in use. Production-ready features like pass-through authentication and operational endpoints are restricted to specific modes.
Streamable HTTP
The HTTP transport allows the MCP server to operate as a remote service accessible over a network. It uses the Starlette ASGI framework to handle requests.
- Capabilities: Supports all authentication modes including OIDC, token-passthrough, and basic-passthrough.
- Operational Endpoints: Provides access to
/healthand/metricsendpoints for monitoring and orchestration probes. - Implementation: Uses
_CredentialsPassthroughASGIand_OAuthDiscoveryInterceptASGImiddleware to handle header extraction and OAuth discovery probes.
Sources: src/infrahub_mcp/server.py:82-84, src/infrahub_mcp/server.py:230-234, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:280-282
Standard I/O (stdio)
The stdio transport enables local integration with tools like Claude Desktop or Cursor by communicating over standard input and output streams.
- Capabilities: Operates with environment variable credentials only (equivalent to
auth_mode=none). - Limitations: Does not support passthrough authentication, health checks, or metrics endpoints.
- Entry Point: Triggered by direct invocation of the server script.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:20-21, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:280-282
In-Memory (Internal)
The In-Memory transport is used exclusively for integration testing. It allows a Client to interact directly with the mcp server instance without network overhead.
- Usage: Bypasses the ASGI auth and transport layers entirely.
- Validation: Still executes FastMCP-level middleware, such as
ReadOnlyMiddlewareandAuditMiddleware.
Sources: specs/001-infrahub-testcontainers/research.md:38-50
Transport Feature Matrix
The following table summarizes the availability of key features across different transport modes.
| Feature | HTTP Transport | Stdio Transport | In-Memory (Test) |
|---|---|---|---|
| Authentication | OIDC, Passthrough, Token, Basic | Environment Vars Only | Direct SDK Client |
| Operational Endpoints | /health, /metrics available | Not available | Not applicable |
| Middleware Execution | Full ASGI + FastMCP Stack | FastMCP Stack | FastMCP Stack Only |
| Concurrency | Multi-session supported | Single local session | Synchronous/Async Test |
Sources: src/infrahub_mcp/server.py:270-275, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:280-285, specs/001-infrahub-testcontainers/research.md:46-52
Data Flow Architecture
The data flow depends on the entry point and the transport wrapper applied to the FastMCP server instance.
The diagram shows how different client types connect through specific entry points to their respective transport layers before reaching the core FastMCP server logic and the Infrahub SDK.
Sources: src/infrahub_mcp/server.py:64-70, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:275-279, specs/001-infrahub-testcontainers/research.md:38-42
Implementation Details
ASGI Middleware for HTTP
When using the HTTP transport, the server wraps the ASGI application with specific middleware to handle credential extraction from HTTP headers.
# src/infrahub_mcp/server.py:230-248
class _CredentialsPassthroughASGI:
"""ASGI middleware that extracts caller credentials from an HTTP header."""
def __init__(self, app: "ASGIApp", *, header: str = "Authorization") -> None:
self._app = app
self._header = header.lower().encode("latin-1")
async def __call__(self, scope: dict, receive: Any, send: Any) -> None:
if scope["type"] == "http":
headers = dict(scope.get("headers", []))
raw = headers.get(self._header, b"").decode("latin-1").strip()
# ... extraction logic ...
Sources: src/infrahub_mcp/server.py:230-248
Transport Selection Logic
The server identifies the required ASGI middleware based on the configured auth_mode, which is intrinsically tied to the transport capability.
# src/infrahub_mcp/server.py:298-305
def get_asgi_middleware() -> list[object]:
"""Return Starlette ASGI middleware for the current auth mode."""
from starlette.middleware import Middleware as StarletteMiddleware
middlewares: list[object] = []
if _config.auth_mode in {AUTH_MODE_TOKEN_PASSTHROUGH, AUTH_MODE_BASIC_PASSTHROUGH}:
middlewares.append(StarletteMiddleware(_CredentialsPassthroughASGI, header=_config.token_passthrough_header))
if _config.auth_mode != AUTH_MODE_OIDC:
middlewares.append(StarletteMiddleware(_OAuthDiscoveryInterceptASGI))
return middlewares
Sources: src/infrahub_mcp/server.py:298-305
Security and Compliance
The choice of transport mode impacts the security boundary of the server.
- Protocol Compliance: The server MUST behave as a well-formed MCP endpoint regardless of transport mode.
- Credential Isolation: HTTP transport uses
ContextVarto store per-request credentials extracted by ASGI middleware, preventing leakage between requests. - Fail-Closed Auth: In passthrough modes (HTTP-only), the server rejects tool calls if no credential is present in the headers.
Sources: dev/constitution.md:26-30, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:204-206, src/infrahub_mcp/server.py:249-253
Transport modes allow the Infrahub MCP server to be flexible across different usage scenarios while maintaining strict security and protocol standards. HTTP is the preferred mode for shared, production environments, while stdio serves local development and direct assistant integrations.