MCP Hangar is a policy enforcement plane for Model Context Protocol (MCP) server clusters, positioned at the invocation path, the only seam where real-time mediation is possible, providing a unified lifecycle, policy, and telemetry channel for the entire MCP server cluster. The project is written in Python, self-hosted, MIT licensed, and does not offer a SaaS version.
Purpose and Background
In MCP, the tool list is a client-cached hint; the invocation path is the only surface where the provider can mediate in real time. Governance primitives such as revocation, per-tenant scoping, and auditing all attach here. Hangar enforces deterministic policy on the invocation path, and the resulting outcomes are reproducible from the policy that produced them; it does not do anomaly scoring and does not rely on learned baselines.
Key Capabilities
- L7 egress policy: allow/deny according to MCP semantics, able to specify which upstream, which tool, and which parameters, deterministically and reproducibly.
- Tool schema digest pinning: if an upstream changes the schema of a pinned tool, fail closed rather than silently serving a different tool. Can be pinned per caller via tool_projection.pins, or pinned per tenant (requires authentication).
- Authentication and RBAC: supports API keys and OIDC/JWT identities, role-based access, and RFC 8707 audience binding; the first administrator can be bootstrapped with mcp-hangar auth bootstrap-admin, and every invocation carries the verified principal into the audit record.
- Per-tenant tool projection: the front door mode presents a different executable surface to each caller, and fails closed for unknown identities.
- Human-in-the-loop approval: gates invocations on an explicit decision, authorized and attributed to a real principal; delivery channels are pluggable, and the core includes no vendor integrations.
- Governed task relay: Hangar intervenes in the SEP-2663 task lifecycle, but does not itself become an executor, and contains no scheduler, job runner, or result store.
- Attributable auditing: identity-attributed audit records can be exported as CEF, LEEF 2.0, RFC 5424 syslog, or JSON-lines, and support OTLP.
- Cluster operation support: parallel tool invocation (a single hangar_call fans out concurrently to multiple MCP servers and returns the results uniformly); lifecycle management (lazy startup, health checks, single-flight cold start, idle shutdown, per-server circuit breaking); hot configuration reLoad (add/remove servers and tools via file watching, no restart required); OAuth entry point (published as an RFC 9728 protected resource, challenging external proxies for validated tokens); built-in observability (OpenTelemetry tracing, Prometheus metrics, structured logging).
Usage
It can be installed with the installer, at the path ~/.mcp-hangar/bin/mcp-hangar. Running init detects MCP clients (Claude Code, Cursor, Claude Desktop), writes configuration, starts servers one by one to verify availability, and records digest pins for each tool while running; after restarting the client, an mcp-hangar server appears in the client alongside existing MCP servers. Existing entries remain unchanged, and once a server is listed under mcp_servers in the configuration written by init, it is behind Hangar.
For manual configuration, under stdio transport, the process that spawns Hangar is the trust boundary, and there is no credential channel, so the caller is declared by auth.stdio.principal (ADR-026); under HTTP there is no default declaration, and Hangar refuses to bind a non-loopback interface without authentication. For a quick demo, pass --unsafe-no-auth; for production use, configure the auth block. The demo configuration file is demo.yaml, and you can point to it by replacing the mcp-hangar entry in the configuration; the demo upstream is located at examples/rugpull/, and the full walkthrough is in quickstart.
Digest pin check: mcp-hangar pin --check prints two digests and exits with exit code 1, making it suitable for CI or pre-commit hooks; --write can adopt changes after confirmation.
Configuration note: the tools: key for each server accepts two forms that look similar but have opposite meanings. The list form only allows tools to be listed before the provider starts; it is not an access policy and cannot survive after startup—the provider's dynamic tools/list is authoritative and completely replaces it, so tools that are statically listed but not returned by the provider will be uncallable and will fail on invocation with Tool not found: <name>. The dictionary form is the access policy, supporting glob patterns and three-level merging. See the configuration reference for the full semantics.
Applicable scenarios
Suitable for organizations that need deterministic governance for MCP server clusters, attributable auditing and compliance export, tenant-isolated tool access, digest pinning for high-risk tool changes, and validation of tool schema changes in CI.
Limitations and notes
Self-hosted only, no SaaS version; the core does not include vendor approval integration; human approval delivery channels must be plugged in by yourself; the runtime environment is Python; authentication configuration should be completed before use, otherwise HTTP binding will be refused. For details on release dates, specific pricing, performance metrics, and the compatible version matrix, refer to the official documentation and the release compatibility matrix. The project has been published in the official MCP Registry (io.mcp-hangar/hangar); that entry describes the PyPI package launched via stdio, not a hosted instance. The name and logo are not covered by the MIT license and use CC BY-ND 4.0; they may be redistributed as-is but may not be modified or used for naming/branding forks or derivatives.
