feat: Add MCP server registry with tool-level access control

[rsharath]

Summary

Add a built-in MCP (Model Context Protocol) server registry that allows administrators to register known MCP servers, manage their OAuth credentials, and enforce tool-level access control. This enables agents authenticated via ZeroID to securely connect to MCP servers with scoped permissions.

Motivation

As MCP adoption grows, agents need to authenticate with many MCP servers (GitHub, Slack, Notion, Linear, Sentry, etc.). Today each agent must independently manage MCP server credentials and there's no centralized way to:

• Control which agents can access which MCP servers
• Restrict access to specific tools within an MCP server
• Audit agent-to-MCP-server interactions
• Manage OAuth client registrations for MCP servers in one place

A registry provides centralized governance over agent-to-tool access.

Requirements

MCP Server Registry

• New mcp_servers table: id, account_id, project_id, name, slug, description, base_url, auth_type (oauth2, api_key, bearer, none), status (active/disabled), metadata, created_at, updated_at
• CRUD endpoints under /api/v1/mcp-servers/
• Support registering custom MCP servers and well-known providers
• Store OAuth client credentials (client_id, encrypted client_secret) per MCP server per tenant
• Support RFC 7591 dynamic client registration for MCP servers that support it

Tool Registry

• New mcp_tools table: id, mcp_server_id, name, description, input_schema (JSON), requires_approval (bool), status
• Auto-discovery: fetch tool list from MCP server's tools/list endpoint
• Manual tool registration for servers that don't support discovery
• Tool-level status (enabled/disabled) per tenant

Access Control

• New mcp_access_policies table: id, account_id, project_id, identity_id (nullable — applies to all if null), identity_type (nullable), mcp_server_id, allowed_tools (array, null = all), denied_tools (array), max_calls_per_hour (rate limit), requires_approval (bool), status
• Policy evaluation: when an agent requests MCP server access, check policies to determine allowed tools
• Support identity-level, identity-type-level, and project-wide policies
• Deny-by-default: agents have no MCP access unless a policy grants it

Token Issuance for MCP Access

• New scope: mcp:<server_slug> and mcp:<server_slug>:<tool_name> for fine-grained tool access
• When agent requests mcp:github scope, ZeroID checks access policy and issues token with allowed tool list in claims
• MCP access tokens carry mcp_servers claim listing allowed servers and tools:

  {
    "mcp_servers": [
      {
        "slug": "github",
        "tools": ["create_issue", "list_repos", "search_code"]
      }
    ]
  }

Proxy / Credential Vending (Optional, Phase 2)

• Token exchange endpoint: agent exchanges ZeroID token for MCP-server-specific OAuth token
• ZeroID acts as credential broker — agent never sees raw MCP server credentials
• Automatic token refresh for MCP server OAuth tokens

Admin Endpoints

• POST /api/v1/mcp-servers/ — register MCP server
• GET /api/v1/mcp-servers/ — list registered servers
• GET /api/v1/mcp-servers/{id} — get server details + tools
• PUT /api/v1/mcp-servers/{id} — update server config
• DELETE /api/v1/mcp-servers/{id} — remove server
• POST /api/v1/mcp-servers/{id}/discover — trigger tool discovery
• POST /api/v1/mcp-servers/{id}/policies — create access policy
• GET /api/v1/mcp-servers/{id}/policies — list access policies

Integration with Existing Features

• Credential policies can restrict mcp:* scopes
• CAE signals can revoke MCP access tokens
• Cascade revocation applies to MCP-scoped delegated tokens
• Audit trail for MCP access policy changes and token issuance

Non-Goals (for initial implementation)

• Acting as a full MCP proxy (forwarding tool calls) — this is a registry and access control layer
• Built-in connectors for specific MCP servers (just the registry framework)
• MCP server health monitoring

References

• Model Context Protocol Specification
• MCP Authorization (OAuth 2.1)
• RFC 7591 - Dynamic Client Registration

[rsharath]

Closing — the MCP server registry, tool discovery, credential vending, and access policy enforcement belong in highflame-firehog (the MCP gateway), not in the identity server. Opening a smaller scoped issue for the ZeroID side: MCP scope vocabulary and claims enrichment.