046 API Reference Cbd47fe6

MCP Gateway Registry - Complete API Reference

This document provides a comprehensive overview of all 49 API endpoints available in the MCP Gateway Registry, organized by category with authentication requirements, request/response specifications, and OpenAPI documentation links.

Table of Contents

1. API Categories
2. Authentication Schemes
3. A2A Agent Management APIs
4. Anthropic MCP Registry API v0
5. Internal Server Management APIs
6. Authentication & Login APIs
7. Health Monitoring APIs
8. Discovery & Well-Known Endpoints
9. Utility Endpoints
10. Response Codes & Error Handling
11. OpenAPI Specifications

API Categories

Authentication Schemes

1. JWT Bearer Token (Nginx-Proxied Auth)

Used by: A2A Agent APIs, Anthropic Registry API v0

How it works:

• Client sends JWT token in Authorization: Bearer <token> header
• Nginx validates token via /validate endpoint against auth-server
• Auth-server validates token against Keycloak
• Token scopes determine user permissions

Token Sources:

• Keycloak M2M service account (mcp-gateway-m2m)
• User tokens generated via /api/tokens/generate

Example:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ..." \
  http://localhost/v0.1/agents

2. Session Cookie (Enhanced Auth)

Used by: UI Server Management, Health Monitoring (WebSocket), Auth status endpoints

How it works:

• User logs in via OAuth2 (Keycloak)
• Auth-server sets mcp_gateway_session cookie
• Browser automatically includes cookie in subsequent requests
• Registry validates cookie against auth-server

Example:

curl -b "mcp_gateway_session=<session_value>" \
  http://localhost/api/servers

3. HTTP Basic Auth

Used by: Internal Admin Endpoints

How it works:

• Credentials: ADMIN_USER:ADMIN_PASSWORD from environment
• Sent in Authorization: Basic <base64> header
• Used for internal mcpgw-server operations

Example:

curl -u admin:password http://localhost/api/internal/register \
  -d "service_path=/example"

4. Public (No Authentication)

Used by: Discovery endpoints, login page, OAuth2 providers list

Endpoints:

• GET /.well-known/mcp-servers
• GET /api/auth/login
• GET /api/auth/providers
• GET /health

A2A Agent Management APIs

File: registry/api/agent_routes.py Route Prefix: /api Authentication: JWT Bearer Token (nginx_proxied_auth)

1. Register Agent

Endpoint: POST /api/agents/register

Purpose: Register a new A2A agent in the registry

Authentication: Requires publish_agent scope

Request Body:

{
  "name": "string",
  "description": "string",
  "path": "/agent-name",
  "url": "https://example.com/agent",
  "version": "1.0.0",
  "provider": "anthropic|custom|other",
  "security_schemes": {
    "scheme_name": {
      "type": "bearer|api_key|oauth2|etc",
      "description": "string"
    }
  },
  "skills": [
    {
      "name": "skill_name",
      "description": "string",
      "input_schema": {}
    }
  ],
  "tags": "string, comma, separated",
  "visibility": "public|private|internal",
  "license": "MIT|Apache-2.0|etc"
}

Response: 201 Created

{
  "message": "Agent registered successfully",
  "agent": {
    "name": "string",
    "path": "/agent-name",
    "url": "https://example.com/agent",
    "num_skills": 5,
    "registered_at": "2025-11-01T04:53:56.228791+00:00",
    "is_enabled": false
  }
}

Error Codes:

• 409 Conflict - Agent path already exists
• 422 Unprocessable Entity - Validation error (invalid JSON, missing fields)
• 403 Forbidden - User lacks publish_agent permission

2. List Agents

Endpoint: GET /api/agents

Purpose: List all agents, optionally filtered

Authentication: Optional (results filtered by user permissions)

Query Parameters:

• query (optional, string) - Search query string
• enabled_only (optional, boolean, default: false) - Show only enabled agents
• visibility (optional, string) - Filter by visibility level

Response: 200 OK

{
  "agents": [
    {
      "name": "string",
      "path": "/agent-name",
      "description": "string",
      "is_enabled": true,
      "total_count": 5
    }
  ]
}

3. Get Single Agent

Endpoint: GET /api/agents/{path:path}

Purpose: Get a single agent by path

Authentication: JWT Bearer Token required

Path Parameter:

• path - Agent path (e.g., /code-reviewer)

Response: 200 OK

{
  "name": "Code Reviewer Agent",
  "path": "/code-reviewer",
  "description": "string",
  "url": "https://example.com/agents/code-reviewer",
  "version": "1.0.0",
  "skills": [
    {
      "name": "review_code",
      "description": "string"
    }
  ],
  "is_enabled": true
}

Error Codes:

• 404 Not Found - Agent doesn't exist
• 403 Forbidden - User not authorized

4. Update Agent

Endpoint: PUT /api/agents/{path:path}

Purpose: Update an existing agent

Authentication: Requires modify_service permission and ownership

Path Parameter:

• path - Agent path

Request Body: Same as registration request

Response: 200 OK with updated agent card

Error Codes:

• 404 Not Found - Agent doesn't exist
• 403 Forbidden - User lacks modify permission
• 422 Unprocessable Entity - Validation error

5. Delete Agent

Endpoint: DELETE /api/agents/{path:path}

Purpose: Delete an agent from registry

Authentication: Requires admin permission or agent ownership

Path Parameter:

• path - Agent path

Response: 204 No Content

Error Codes:

• 404 Not Found - Agent doesn't exist
• 403 Forbidden - User lacks delete permission

6. Toggle Agent Status

Endpoint: POST /api/agents/{path:path}/toggle

Purpose: Enable or disable an agent

Authentication: Requires toggle_service permission

Path Parameter:

• path - Agent path

Query Parameter:

• enabled (boolean) - True to enable, false to disable

Response: 200 OK

{
  "path": "/agent-name",
  "is_enabled": true,
  "message": "Agent enabled successfully"
}

Error Codes:

• 404 Not Found - Agent doesn't exist
• 403 Forbidden - User lacks toggle permission

7. Discover Agents by Skills

Endpoint: POST /api/agents/discover

Purpose: Find agents that match required skills

Authentication: Optional

Request Body:

{
  "skills": ["skill1", "skill2"],
  "tags": ["optional", "filters"]
}

Query Parameter:

• max_results (optional, integer, default: 10, max: 100)

Response: 200 OK

{
  "agents": [
    {
      "path": "/agent-name",
      "name": "string",
      "relevance_score": 0.95,
      "matching_skills": ["skill1"]
    }
  ]
}

Error Codes:

• 400 Bad Request - No skills provided

8. Discover Agents Semantically

Endpoint: POST /api/agents/discover/semantic

Purpose: Find agents using NLP semantic search (FAISS vector search)

Authentication: Optional

Query Parameters:

• query (required, string) - Natural language query (e.g., "Find agents that can analyze code")
• max_results (optional, integer, default: 10, max: 100)

Response: 200 OK

{
  "agents": [
    {
      "path": "/code-reviewer",
      "name": "Code Reviewer Agent",
      "relevance_score": 0.92,
      "description": "Analyzes code for issues..."
    }
  ]
}

Error Codes:

• 400 Bad Request - Empty query
• 500 Internal Server Error - Search error

Anthropic MCP Registry API v0

This section implements the official Anthropic MCP Registry API specification for standard server discovery and agent discovery using the same API patterns.

MCP Servers (v0)

File: registry/api/registry_routes.py Route Prefix: /v0 (from REGISTRY_CONSTANTS.ANTHROPIC_API_VERSION) Authentication: JWT Bearer Token

1. List MCP Servers

Endpoint: GET /v0/servers

Purpose: List all MCP servers with cursor-based pagination

Query Parameters:

• cursor (optional, string) - Pagination cursor from previous response
• limit (optional, integer, default: 100, max: 1000) - Max items per page

Response: 200 OK

{
  "servers": [
    {
      "id": "io.mcpgateway/example-server",
      "name": "Example Server",
      "description": "string",
      "homepage": "https://example.com",
      "resources": [
        {
          "uri": "example://resource",
          "mimeType": "text/plain"
        }
      ]
    }
  ],
  "_meta": {
    "pagination": {
      "hasMore": false,
      "nextCursor": null
    }
  }
}

2. List Server Versions

Endpoint: GET /v0/servers/{serverName:path}/versions

Purpose: List all versions for a specific server

Path Parameter:

• serverName - URL-encoded reverse-DNS name (e.g., io.mcpgateway%2Fexample-server)

Response: 200 OK with versions array (currently one version per server)

Error Codes:

• 404 Not Found - Server not found or user lacks access

3. Get Server Version Details

Endpoint: GET /v0/servers/{serverName:path}/versions/{version}

Purpose: Get detailed information about a specific server version

Path Parameters:

• serverName - URL-encoded server name
• version - Version string or latest

Response: 200 OK with complete server details including tools

Error Codes:

• 404 Not Found - Server/version not found or user lacks access

Internal Server Management APIs

UI Management Endpoints

File: registry/api/server_routes.py Route Prefix: /api Authentication: Session Cookie (enhanced_auth)

1. Dashboard/Root

Endpoint: GET /api/

Purpose: Main dashboard showing services based on user permissions

Query Parameters:

• query (optional, string) - Search services

Response: HTML page with filtered service list

2. Get Servers JSON

Endpoint: GET /api/servers

Purpose: Get servers data as JSON for React frontend

Query Parameters:

• query (optional, string)

Response: 200 OK

{
  "servers": [
    {
      "path": "/example",
      "name": "Example Server",
      "description": "string",
      "is_enabled": true,
      "health_status": "healthy"
    }
  ]
}

3. Toggle Service

Endpoint: POST /api/toggle/{service_path:path}

Purpose: Enable/disable a service

Authentication: Requires toggle_service UI permission

Form Parameters:

• enabled (boolean)

Response: 200 OK with new status

Error Codes:

• 404 Not Found - Service doesn't exist
• 403 Forbidden - User lacks toggle permission
• 500 Internal Server Error - Toggle operation failed

4. Register Service (UI)

Endpoint: POST /api/register

Purpose: Register new service via dashboard

Authentication: Requires register_service UI permission

Form Parameters:

• name, description, path, proxy_pass_url, tags, num_tools, num_stars, is_python, license

Response: 201 Created

Error Codes:

• 400 Bad Request - Service already exists
• 403 Forbidden - User lacks register permission

5. Edit Service Form

Endpoint: GET /api/edit/{service_path:path}

Purpose: Show edit form for service

Authentication: Requires modify_service UI permission

Response: HTML edit form

6. Update Service

Endpoint: POST /api/edit/{service_path:path}

Purpose: Handle service edit submission

Authentication: Requires modify_service UI permission

Form Parameters: Same as register

Response: 303 See Other (redirect to home)

7. Token Generation Page

Endpoint: GET /api/tokens

Purpose: Show JWT token generation form

Response: HTML form

8. Get Server Details

Endpoint: GET /api/server_details/{service_path:path}

Purpose: Get detailed server info by path or all servers

Path Parameter:

• service_path - Service path or all

Response: 200 OK with server details

9. Get Service Tools

Endpoint: GET /api/tools/{service_path:path}

Purpose: Get tools list for service

Path Parameter:

• service_path - Service path or all

Response: 200 OK

{
  "tools": [
    {
      "name": "tool_name",
      "description": "string",
      "inputSchema": {}
    }
  ]
}

Error Codes:

• 404 Not Found - Service not found
• 400 Bad Request - Service disabled
• 403 Forbidden - User lacks access

10. Refresh Service

Endpoint: POST /api/refresh/{service_path:path}

Purpose: Refresh service health and tools

Authentication: Requires health_check_service permission

Response: 200 OK with refresh status

Internal Admin Endpoints

Authentication: HTTP Basic Auth (admin credentials)

11. Internal Register Service

Endpoint: POST /api/internal/register

Purpose: Internal service registration for mcpgw-server

Form Parameters: All registration parameters + overwrite, auth_provider, auth_type, supported_transports, headers, tool_list_json

Response: 201 Created or 409 Conflict

Features: Auto-enables services, updates scopes.yml

12. Internal Remove Service

Endpoint: POST /api/internal/remove

Form Parameters: service_path

Response: 200 OK or 404/500 error

13. Internal Toggle Service

Endpoint: POST /api/internal/toggle

Form Parameters: service_path

Response: 200 OK with new state

14. Internal Healthcheck

Endpoint: POST /api/internal/healthcheck

Response: Health status for all servers

15. Add Server to Groups

Endpoint: POST /api/internal/add-to-groups

Form Parameters:

• server_name - Server name
• group_names - Comma-separated group names

Response: 200 OK with result

16. Remove Server from Groups

Endpoint: POST /api/internal/remove-from-groups

Form Parameters: Same as add-to-groups

Response: 200 OK

17. Internal List Services

Endpoint: GET /api/internal/list

Response: 200 OK with all services and health status

18. Create Group

Endpoint: POST /api/internal/create-group

Form Parameters:

• group_name
• description (optional)
• create_in_idp (optional)

Response: 200 OK

19. Delete Group

Endpoint: POST /api/internal/delete-group

Form Parameters:

• group_name
• delete_from_idp (optional)
• force (optional)

Response: 200 OK

Note: Prevents deletion of system groups

20. List Groups

Endpoint: GET /api/internal/list-groups

Query Parameters:

• include_keycloak (default: true)
• include_scopes (default: true)

Response: 200 OK with synchronized groups info

21. Generate JWT Token

Endpoint: POST /api/tokens/generate

Purpose: Generate JWT token for authenticated user

Request Body:

{
  "requested_scopes": ["optional", "scopes"],
  "expires_in_hours": 8,
  "description": "Token description"
}

Response: 200 OK

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 28800,
  "refresh_token": "string (if enabled)",
  "scope": "space separated scopes"
}

22. Admin Get Keycloak Token

Endpoint: GET /api/admin/tokens

Purpose: Admin-only endpoint to retrieve M2M tokens

Authentication: Admin users only

Response: 200 OK with access token

Error Codes:

• 403 Forbidden - Non-admin user
• 500 Internal Server Error - Configuration error

Authentication & Login APIs

File: registry/auth/routes.py Route Prefix: /api/auth

1. Login Form

Endpoint: GET /api/auth/login

Purpose: Show login form with OAuth2 providers

Query Parameters:

• error (optional) - Error message

Response: HTML login form

2. OAuth2 Redirect

Endpoint: GET /api/auth/auth/{provider}

Purpose: Redirect to auth server for OAuth2 login

Path Parameter:

• provider - OAuth2 provider (e.g., keycloak, cognito)

Response: 302 Redirect to auth server

3. OAuth2 Callback

Endpoint: GET /api/auth/auth/callback

Purpose: Handle OAuth2 callback

Query Parameters:

• error (optional)
• details (optional)

Response: 302 Redirect to home or login with error

4. Login Submit (Form)

Endpoint: POST /api/auth/login

Purpose: Handle login form submission

Form Parameters:

• username
• password

Response: 302 Redirect to home on success, 401 on failure

5. Logout (GET)

Endpoint: GET /api/auth/logout

Purpose: Handle logout via GET

Response: 302 Redirect to login (clears session)

6. Logout (POST)

Endpoint: POST /api/auth/logout

Purpose: Handle logout via POST

Response: 302 Redirect to login (clears session)

7. OAuth2 Providers List

Endpoint: GET /api/auth/providers

Purpose: Get available OAuth2 providers

Authentication: None (public)

Response: 200 OK

{
  "providers": [
    {
      "name": "keycloak",
      "display_name": "Keycloak",
      "icon": "keycloak"
    }
  ]
}

Health Monitoring APIs

File: registry/health/routes.py Route Prefix: /api/health

1. Health Status WebSocket

Endpoint: WebSocket /api/health/ws/health_status

Purpose: Real-time health status updates via WebSocket

Authentication: Session cookie required

Messages: Periodic health status broadcasts

Features:

• Authenticated connections only
• Ping/pong keep-alive
• Graceful disconnect handling

2. Health Status HTTP

Endpoint: GET /api/health/ws/health_status

Purpose: Get health status via HTTP (WebSocket fallback)

Authentication: None

Response: 200 OK with health status JSON

3. WebSocket Statistics

Endpoint: GET /api/health/ws/stats

Purpose: Get WebSocket performance statistics

Response: 200 OK

{
  "active_connections": 5,
  "total_messages_sent": 1234,
  "uptime_seconds": 86400
}

Discovery & Well-Known Endpoints

File: registry/api/wellknown_routes.py Route Prefix: /.well-known Authentication: None (public)

MCP Servers Discovery

Endpoint: GET /.well-known/mcp-servers

Purpose: Public MCP server discovery for client tools

Response: 200 OK

{
  "servers": [
    {
      "id": "io.mcpgateway/example",
      "name": "Example Server",
      "description": "string",
      "mcp": {
        "transport": "streamable-http",
        "url": "https://gateway.example.com/example/"
      }
    }
  ],
  "_meta": {
    "registry": "MCP Gateway Registry",
    "updated_at": "2025-11-01T04:53:56Z"
  }
}

Features:

• Server filtering by enabled status
• Authentication info included
• Tools preview
• Public cache headers with configurable TTL

Utility Endpoints

1. Current User Info

Endpoint: GET /api/auth/me

Purpose: Get current user information for React auth context

Authentication: Session cookie (enhanced_auth)

Response: 200 OK

{
  "username": "admin",
  "email": "admin@example.com",
  "auth_method": "oauth2",
  "provider": "keycloak",
  "scopes": ["mcp-registry-admin"],
  "groups": ["mcp-registry-admin", "mcp-servers-unrestricted"],
  "is_admin": true
}

2. Health Check

Endpoint: GET /health

Purpose: Simple health check for load balancers

Authentication: None (public)

Response: 200 OK

{
  "status": "healthy",
  "service": "mcp-gateway-registry"
}

Response Codes & Error Handling

Success Responses

Client Error Responses

Server Error Responses

Error Response Format

{
  "detail": "Human-readable error message",
  "error_code": "optional_error_code",
  "request_id": "unique_request_identifier"
}

OpenAPI Specifications

Access OpenAPI Specifications

FastAPI automatically generates OpenAPI (Swagger) specifications:

Available Endpoints:

• OpenAPI JSON: GET /openapi.json
• Swagger UI: GET /docs
• ReDoc: GET /redoc

Local Access:

curl http://localhost:7860/openapi.json

Browser Access:

• Swagger UI: http://localhost:7860/docs
• ReDoc: http://localhost:7860/redoc

Generate Spec Files

To download and save OpenAPI specs:

# Get full OpenAPI spec as JSON
curl -s http://localhost:7860/openapi.json > openapi.json

# Filter for specific tags
curl -s http://localhost:7860/openapi.json | \
  jq '.paths | keys[] | select(contains("/agents"))' > agents-endpoints.json

# Generate Swagger YAML (requires conversion)
curl -s http://localhost:7860/openapi.json | \
  python3 -c "import sys, json, yaml; print(yaml.dump(json.load(sys.stdin)))" > openapi.yaml

Using Generated Specs

1. Code Generation:

   # Generate Python client
   openapi-generator-cli generate -i openapi.json -g python -o ./python-client
   
   # Generate JavaScript client
   openapi-generator-cli generate -i openapi.json -g javascript -o ./js-client
   

2. API Documentation: Import into Postman, Insomnia, or other API tools

3. Validation: Use openapi-spec-validator to validate the spec

Summary Table

Quick Reference by Use Case

I want to register an agent

• Endpoint: POST /api/agents/register
• Auth: JWT Bearer Token with publish_agent scope
• Documentation: See A2A Agent Management APIs > Register Agent

I want to discover agents by capability

• Endpoint: POST /api/agents/discover/semantic
• Auth: Optional
• Query: Natural language query
• Documentation: See A2A Agent Management APIs > Discover Agents Semantically

I want to list all servers (Anthropic API format)

• Endpoint: GET /v0/servers
• Auth: JWT Bearer Token
• Documentation: See Anthropic MCP Registry API v0 > List MCP Servers

I want to generate a JWT token

• Endpoint: POST /api/tokens/generate
• Auth: Session Cookie
• Documentation: See Internal Server Management APIs > Generate JWT Token

I want to find servers I have access to

• Endpoint: GET /api/servers
• Auth: Session Cookie
• Documentation: See Internal Server Management APIs > Get Servers JSON

Version History