MCP Gateway Registry API Documentation¶

This document provides a comprehensive overview of all API endpoints available in the MCP Gateway Registry service.

Table of Contents¶

Authentication
OAuth2 Login
Logout
Server Management
Register a New Service
Toggle Service Status
Edit Service Details
API Endpoints
Get Server Details
Get Service Tools
Refresh Service
WebSocket Endpoints
Health Status Updates

Authentication¶

IMPORTANT: Most endpoints in this API require authentication via OAuth2 (Keycloak). Users authenticate through the browser-based OAuth2 flow, which sets a session cookie. The examples below use -b cookies.txt to include the session cookie in requests. For programmatic API access, use a JWT Bearer token obtained from your OAuth2 provider.

Authentication is handled via OAuth2 providers (Keycloak). Navigate to /login in your browser to initiate the OAuth2 flow.

URL: /login Method: GET Response: Login page with OAuth2 provider buttons

URL: /auth/{provider} Method: GET Description: Redirects to the OAuth2 provider for authentication. After successful authentication, a session cookie is set automatically.

Logout¶

Logs out the current user by invalidating their session.

URL: /logout
Method: POST
Authentication: Required (session cookie)
Response: Redirects to /login

Example:

curl -X POST http://localhost:7860/logout \
  -b cookies.txt

Server Management¶

Note: All endpoints in this section require authentication via a session cookie obtained from the OAuth2 login flow.

Register a New Service¶

Registers a new MCP service with the gateway.

URL: /register
Method: POST
Content-Type: application/x-www-form-urlencoded
Authentication: Required (session cookie)
Parameters: - name (required): Display name of the service - description (required): Description of the service - path (required): URL path for the service - proxy_pass_url (required): URL to proxy requests to - tags (optional): Comma-separated list of tags - num_tools (optional): Number of tools provided by the service - num_stars (optional): Star rating for the service - is_python (optional): Whether the service is Python-based - license (optional): License information - metadata (optional): JSON object with custom metadata for organization, compliance, and integration tracking. Fully searchable via semantic search.

Metadata Examples:

{
  "team": "data-platform",
  "owner": "alice@example.com",
  "compliance_level": "PCI-DSS",
  "cost_center": "engineering",
  "deployment_region": "us-east-1"
}

Response: - Success: JSON response with status code 201 - Failure: JSON response with error details

Example:

# Uses the session cookie from the login request
curl -X POST http://localhost:7860/register \
  -b cookies.txt \
  -d "name=Weather Service&description=Provides weather forecasts&path=/weather&proxy_pass_url=http://localhost:8000&tags=weather,forecast&num_tools=3&num_stars=4&is_python=true&license=MIT"

Toggle Service Status¶

Enables or disables a registered service.

URL: /toggle/{service_path}
Method: POST
Content-Type: application/x-www-form-urlencoded
Authentication: Required (session cookie)
URL Parameters: - service_path: Path of the service to toggle Form Parameters: - enabled: "on" to enable, omit to disable

Response: JSON with updated service status

Example:

# Enable a service (requires session cookie)
curl -X POST http://localhost:7860/toggle/weather \
  -b cookies.txt \
  -d "enabled=on"

# Disable a service (requires session cookie)
curl -X POST http://localhost:7860/toggle/weather \
  -b cookies.txt

Edit Service Details¶

Updates the details of an existing service.

URL: /edit/{service_path}
Method: POST
Content-Type: application/x-www-form-urlencoded
Authentication: Required (session cookie)
URL Parameters: - service_path: Path of the service to edit Form Parameters: - name (required): Display name of the service - proxy_pass_url (required): URL to proxy requests to - description (optional): Description of the service - tags (optional): Comma-separated list of tags - num_tools (optional): Number of tools provided by the service - num_stars (optional): Star rating for the service - is_python (optional): Whether the service is Python-based - license (optional): License information

Response: Redirects to the main page on success

Example:

# Requires session cookie from login
curl -X POST http://localhost:7860/edit/weather \
  -b cookies.txt \
  -d "name=Weather API&description=Updated weather service&proxy_pass_url=http://localhost:8001&tags=weather,api&num_tools=5&num_stars=5&is_python=true&license=MIT"

API Endpoints¶

Note: All endpoints in this section require authentication via a session cookie obtained from the OAuth2 login flow.

Get Server Details¶

Retrieves detailed information about a registered service.

URL: /api/server_details/{service_path}
Method: GET
Authentication: Required (session cookie)
URL Parameters: - service_path: Path of the service to get details for, or "all" to get details for all services

Response: JSON with server details

Example:

# Get details for a specific service (requires session cookie)
curl -X GET http://localhost:7860/api/server_details/weather \
  -b cookies.txt

# Get details for all services (requires session cookie)
curl -X GET http://localhost:7860/api/server_details/all \
  -b cookies.txt

Get Service Tools¶

Retrieves the list of tools provided by a service.

URL: /api/tools/{service_path}
Method: GET
Authentication: Required (session cookie)
URL Parameters: - service_path: Path of the service to get tools for, or "all" to get tools from all services

Response: JSON with tool details

Example:

# Get tools for a specific service (requires session cookie)
curl -X GET http://localhost:7860/api/tools/weather \
  -b cookies.txt

# Get tools from all services (requires session cookie)
curl -X GET http://localhost:7860/api/tools/all \
  -b cookies.txt

Refresh Service¶

Manually triggers a health check and tool discovery for a service.

URL: /api/refresh/{service_path}
Method: POST
Authentication: Required (session cookie)
URL Parameters: - service_path: Path of the service to refresh

Response: JSON with updated service status

Example:

# Requires session cookie from login
curl -X POST http://localhost:7860/api/refresh/weather \
  -b cookies.txt

WebSocket Endpoints¶

Health Status Updates¶

Provides real-time updates on the health status of all registered services.

URL: /ws/health_status
Protocol: WebSocket
Authentication: Not required (public endpoint)
Response: JSON messages with health status updates

Example using websocat:

First, install websocat:

sudo wget -qO /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl
sudo chmod +x /usr/local/bin/websocat

Then connect to the WebSocket endpoint:

websocat ws://localhost:7860/ws/health_status

This will display the JSON messages with health status updates in real-time in your terminal.

Example using Python:

# Python example using websockets library
import asyncio
import json
import websockets

async def health_status_monitor():
    uri = "ws://localhost:7860/ws/health_status"
    async with websockets.connect(uri) as websocket:
        print("WebSocket connection established")

        while True:
            try:
                # Receive health status updates
                message = await websocket.recv()
                data = json.loads(message)

                print("Health status update received:")
                for path, info in data.items():
                    print(f"Service {path}: {info['status']}")
                    print(f"Last checked: {info['last_checked_iso']}")
                    print(f"Number of tools: {info['num_tools']}")
                    print("---")
            except websockets.exceptions.ConnectionClosed:
                print("Connection closed")
                break

# Run the async function
asyncio.run(health_status_monitor())

Authentication Flow¶

Login: Navigate to /login in your browser and authenticate via your OAuth2 provider (Keycloak). The session cookie is set automatically after successful authentication.
Programmatic Access: For API access, obtain a JWT Bearer token from your OAuth2 provider and include it in the Authorization header:
```
curl -X GET http://localhost:7860/api/server_details/all \
  -H "Authorization: Bearer <your-jwt-token>"
```
Session Expiration: The session cookie is valid for 8 hours. After expiration, you'll need to login again.

API Summary¶

GET /login: Display login page with OAuth2 provider options.
GET /auth/{provider}: Redirect to OAuth2 provider for authentication.
POST /logout: Log out user and invalidate session cookie.
GET /: Main dashboard (web UI, requires authentication).
GET /edit/{service_path}: Edit service form (web UI, requires authentication).
POST /register: Register a new service (requires authentication).
POST /toggle/{service_path}: Enable/disable a service (requires authentication).
POST /edit/{service_path}: Update service details (requires authentication).
GET /api/server_details/{service_path}: Get full details for a service (requires authentication).
GET /api/tools/{service_path}: Get the discovered tool list for a service (requires authentication).
POST /api/refresh/{service_path}: Manually trigger a health check/tool update (requires authentication).
WebSocket /ws/health_status: Real-time connection for receiving server health status updates.

MCP Gateway Registry API Documentation¶

Table of Contents¶

Authentication¶

OAuth2 Login¶

Logout¶

Server Management¶

Register a New Service¶

Toggle Service Status¶

Edit Service Details¶

API Endpoints¶

Get Server Details¶

Get Service Tools¶

Refresh Service¶

WebSocket Endpoints¶

Health Status Updates¶

Authentication Flow¶

API Summary¶