REST API

MCP Hangar exposes a full REST API alongside the MCP protocol layer. The API is mounted at /api/ when running in HTTP mode and provides CRUD operations, real-time WebSocket streams, and operational endpoints.

Quick Start

Start Hangar in HTTP mode:

mcp-hangar serve --http --port 8000

The REST API is available at http://localhost:8000/api/.

# List all mcp_servers
curl http://localhost:8000/api/mcp_servers

# Get system info
curl http://localhost:8000/api/system

# Start a mcp_server
curl -X POST http://localhost:8000/api/mcp_servers/math/start

Authentication

When authentication is enabled, pass your API key in the X-API-Key header:

curl -H "X-API-Key: mcp_your_key_here" http://localhost:8000/api/mcp_servers

See the Authentication guide for setup instructions.

Endpoints Overview

All endpoints return JSON. Error responses follow the envelope format:

{
  "error": "McpServerNotFoundError",
  "message": "MCP Server 'unknown' not found",
  "status_code": 404
}

MCP servers

Groups

Discovery

Note: All discovery endpoints return 404 when no discovery: block is configured. See the Discovery guide for setup.

Configuration

System

Auth Management (Enterprise)

Health Probes and Metrics

These endpoints are outside the /api/ prefix and skip authentication:

WebSockets

See the WebSockets guide for connection details.

Examples

Create a MCP Server

curl -X POST http://localhost:8000/api/mcp_servers \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_server_id": "my-llm",
    "mode": "subprocess",
    "command": ["python", "-m", "llm_server"],
    "idle_ttl_s": 600,
    "description": "LLM inference mcp_server"
  }'

{"mcp_server_id": "my-llm", "created": true}

Create a Group with Members

# Create group
curl -X POST http://localhost:8000/api/groups \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "llm-pool",
    "strategy": "round_robin",
    "min_healthy": 1
  }'

# Add members
curl -X POST http://localhost:8000/api/groups/llm-pool/members \
  -H "Content-Type: application/json" \
  -d '{"member_id": "my-llm", "weight": 1, "priority": 1}'

Export and Diff Configuration

# Export current state
curl -X POST http://localhost:8000/api/config/export

# See what changed vs disk
curl http://localhost:8000/api/config/diff

Register a Discovery Source

curl -X POST http://localhost:8000/api/discovery/sources \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "docker",
    "mode": "additive",
    "enabled": true,
    "config": {"socket_path": "/var/run/docker.sock"}
  }'

CORS

CORS is configured via environment variables:

For production, restrict origins to your dashboard URL:

export MCP_CORS_ORIGINS="https://dashboard.example.com"

Error Handling

All domain exceptions are mapped to HTTP status codes:

The error envelope always contains error (exception class name), message, and status_code.

Full Reference

For complete request/response schemas, see the REST API Reference.