12 -- Auth & RBAC

Prerequisite: 01 -- HTTP Gateway You will need: Running Hangar in HTTP mode Time: 10 minutes Adds: API key authentication and role-based access control

The Problem

Your Hangar instance is accessible to everyone on the network. You need to control who can invoke tools, start MCP servers, or manage configuration. Different teams need different access levels.

The Config

# config.yaml -- Recipe 12: Auth & RBAC
mcp_servers:
  my-mcp:
    mode: remote
    endpoint: "http://localhost:8080"
    health_check_interval_s: 10

auth:                                    # NEW: authentication config
  enabled: true                          # NEW: enable auth
  allow_anonymous: false                 # NEW: require auth for all requests

  api_key:                               # NEW: API key config
    enabled: true                        # NEW: enable API key auth
    header_name: X-API-Key               # NEW: header to read key from

Try It

1. Start Hangar:

   mcp-hangar serve --http --port 8000

2. Try an unauthenticated request -- it fails:

   curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/mcp_servers

   401
   

3. Create an API key:

   curl -X POST http://localhost:8000/api/auth/keys \
     -H "Content-Type: application/json" \
     -d '{"principal_id": "service:my-app", "name": "My App Key"}'

   {"key_id": "...", "raw_key": "mcp_aBcDeFg...", "principal_id": "service:my-app", "name": "My App Key"}

   Save the raw_key -- it is shown only once.

4. Use the key:

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

   {"mcp_servers": [...]}

5. Assign a role:

   curl -X POST http://localhost:8000/api/auth/roles/assign \
     -H "X-API-Key: mcp_admin_key..." \
     -H "Content-Type: application/json" \
     -d '{"principal_id": "service:my-app", "role_name": "developer"}'

6. Set a tool access policy:

   curl -X POST http://localhost:8000/api/auth/policies/provider/my-mcp \
     -H "X-API-Key: mcp_admin_key..." \
     -H "Content-Type: application/json" \
     -d '{"allow_list": ["service:my-app"], "deny_list": []}'

What Just Happened

Enabling auth adds the AuthMiddleware to the HTTP stack. Every request must include a valid API key in the X-API-Key header. The key is hashed and looked up in the auth store. The principal's roles determine what operations are allowed.

Built-in roles:

Tool access policies add fine-grained control per (principal, MCP server, tool) tuple.

Key Config Reference

What's Next

You've secured access. Before going to production, run through the full checklist.

--> 13 -- Production Checklist