Haldir

What Haldir MCP server does

Haldir MCP server provides a governance layer for AI agents that call tools and APIs. It places a controlled boundary between an agent and its upstream tools, allowing teams to apply identity, access, spending, secret-handling, and audit rules to agent activity.

The platform supports scoped agent sessions with permissions and per-session spend limits. Secrets are stored in an encrypted vault and retrieved through access-controlled requests, so the model does not receive credentials directly as part of the normal governance flow. Haldir also records actions in a hash-chained audit trail intended to make later tampering detectable.

Human approvals are available for actions that require review, and webhooks can report related events. The README also describes a compliance evidence endpoint that produces Markdown or JSON evidence packs covering access control, encryption, audit integrity, spend governance, approvals, and outbound alerting.

How it works

An agent sends tool activity through Haldir's proxy. The proxy intercepts each MCP call before it reaches the upstream tool, where Haldir can apply session permissions and policy checks. Approved activity can then be logged to the audit chain, while requests requiring review can enter an approval workflow.

The service exposes an HTTP API and can run against SQLite or Postgres. The documented hosted endpoint is https://haldir.xyz; self-hosted deployments expose the API locally after the Docker Compose stack starts. The Python client can create sessions, store secrets, retrieve secrets with a session identifier, and interact with the governed API.

The Haldir MCP server is useful when an agent must operate with bounded authority rather than unrestricted access to environment variables, payment actions, or external APIs. It is also relevant when an operator needs an inspectable record of agent actions or evidence for an internal compliance process.

Setup and configuration

For the hosted option, the README shows installing the Python package with pip install haldir and configuring a client with an Haldir API key and the hosted base URL. The command-line client supports login, status checks, audit operations, webhook delivery inspection, migration commands, and JSON output for scripts.

Self-hosting requires cloning the repository, copying .env.example to .env, generating a URL-safe 32-byte value, and placing it in HALDIR_ENCRYPTION_KEY. The documented startup command is docker compose up -d; the health endpoint is then available at http://localhost:8000/health. Self-hosted deployments run the API and Postgres according to the repository's Docker Compose configuration, while the service can also use SQLite.

The README identifies HALDIR_PG_POOL_MIN and HALDIR_PG_POOL_MAX as Postgres pool settings and shows DATABASE_URL for enabling a Postgres connection. These are deployment configuration options rather than required values for every installation.

Tools and capabilities

The Haldir MCP server and its API are described as supporting:

• Scoped sessions with permissions and spend caps.
• Encrypted secret storage using AES-256-GCM with access control.
• Hash-chained audit records and audit-chain verification.
• Human approval lifecycles with webhook notifications.
• A proxy that intercepts MCP calls before upstream tools receive them.
• Compliance evidence exports in Markdown and JSON formats.
• CLI operations for service status, audits, webhooks, migrations, and readiness checks.

The project also lists native SDK support for LangChain, CrewAI, AutoGen, and the Vercel AI SDK. The excerpt does not provide a complete inventory of individual MCP tool names or their input schemas.

Limitations and notes

The material does not document a specific MCP client setup command or a complete MCP server launch command, so installation through an MCP client cannot be specified reliably from this excerpt. Hosted use requires an Haldir API key, while self-hosting requires managing the API deployment and encryption key. Cloud use has a free tier and paid plans; self-hosting is described as free and MIT licensed.

Performance figures in the README are benchmark results for particular local hardware, backend, and concurrency settings. They should not be treated as a guarantee for a different deployment. The README also states that the project is accepting design partners, but does not define production support terms or service-level guarantees.