Quick Start

New to this? From install to a governed deny in 10 minutes is the concept behind this page.

Get MCP Hangar running with Claude Desktop in under 30 seconds.

One-Liner Install

curl -sSL https://mcp-hangar.io/install.sh | bash && mcp-hangar init -y && mcp-hangar serve

That's it. Restart Claude Desktop and you have:

• filesystem - Read and write local files
• fetch - Make HTTP requests
• memory - Persistent key-value storage

Prerequisites

• Python 3.11 or later
• Claude Desktop installed (download)
• uvx or npx (for MCP server packages)

Interactive Setup

Prefer a guided experience? Use the wizard:

pip install mcp-hangar
mcp-hangar init

The wizard will:

1. Detect runtimes - finds uvx, npx, docker in your PATH
2. Detect Claude Desktop - finds your Claude Desktop config automatically
3. Select MCP servers - choose which MCP servers to enable
4. Test MCP servers - verify each MCP server starts correctly
5. Update Claude Desktop - automatically configure Claude to use MCP Hangar

Restart Claude Desktop after the wizard completes.

Verify It Works

Check that your MCP servers are configured:

mcp-hangar status

You should see your configured MCP servers listed (they'll show as COLD until first use).

Adding More MCP servers

Add MCP servers anytime with:

mcp-hangar add github     # GitHub integration (needs token)
mcp-hangar add sqlite     # SQLite database access
mcp-hangar add postgres   # PostgreSQL access

Available Bundles

Use bundles to quickly configure common setups:

# Start fresh with a bundle
mcp-hangar init --bundle=developer

Manual Configuration

If you prefer manual setup or need advanced configuration:

1. Create config file

Create ~/.config/mcp-hangar/config.yaml:

mcp_servers:
  # Both are official servers from modelcontextprotocol/servers; the full list,
  # with what each one needs, is in ../guides/OFFICIAL_SERVERS.md
  filesystem:
    mode: subprocess
    command: [npx, -y, "@modelcontextprotocol/server-filesystem"]
    args: [/Users/your-username/Documents]
    idle_ttl_s: 300

  fetch:
    mode: subprocess
    command: [npx, -y, "@modelcontextprotocol/server-fetch"]
    idle_ttl_s: 300

2. Update Claude Desktop config

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-hangar": {
      "command": "mcp-hangar",
      "args": ["serve", "--config", "/Users/your-username/.config/mcp-hangar/config.yaml"]
    }
  }
}

3. Restart Claude Desktop

Troubleshooting

Claude Desktop not found

If the wizard can't find Claude Desktop:

mcp-hangar init --claude-config /path/to/claude_desktop_config.json

MCP Server won't start

Check the MCP server status for errors:

mcp-hangar status mcp-server-name

Gateway refuses to start: "Configured subsystem is not reachable"

From 2.1.0 Hangar checks at startup that every subsystem the configuration demands is actually reachable on the path this process took, and refuses to boot when a security subsystem is missing:

Configured subsystem is not reachable on this server:
approval_gate required by tools.approval_list on mcp_server:payments.
The configuration asks for enforcement this process cannot perform.

It means a tool is on an approval_list but no approval gate service exists — usually because approvals.enabled: false is also set. Starting anyway would run those calls ungated, which is why it is a refusal rather than a warning. Fix it by removing the approval_list entry or re-enabling the gate. To downgrade every such refusal to an error log:

startup_checks:
  enforce: false

There is deliberately no setting that makes an unreachable subsystem silent. Any non-security subsystem in the same state already logs subsystem_configured_but_unreachable at ERROR without blocking the boot — grep your logs for it. See Configuration → startup_checks.

Permission denied

Make sure you have write access to the config directories:

• MCP Hangar config: ~/.config/mcp-hangar/
• Claude Desktop config: ~/Library/Application Support/Claude/ (macOS)

Next Steps

• CLI Reference - All CLI commands and options
• Container MCP servers - Using Docker/Podman MCP servers
• Observability - Metrics and monitoring
• Architecture - Understanding the design