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
Login Form
Login Submission
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. You must first call the /login endpoint to obtain a session cookie, which must be included in all subsequent requests to authenticated endpoints. The examples below use -b cookies.txt to include the session cookie in the requests.

Displays the login form for the MCP Gateway Registry.

URL: /login Method: GET Response: HTML login form

Example:

curl -X GET http://localhost:7860/login

Authenticates a user and creates a session. This endpoint must be called first to obtain the session cookie required for all other authenticated endpoints.

URL: /login Method: POST Content-Type: application/x-www-form-urlencoded Parameters:

username (required): Admin username
password (required): Admin password

Response:

Success: Redirects to / with a session cookie
Failure: Redirects to /login?error=Invalid+username+or+password

Example:

# Save the session cookie to cookies.txt for use in subsequent requests
curl -X POST http://localhost:7860/login \
  -d "username=admin&password=password" \
  -c cookies.txt

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 the session cookie obtained from the /login endpoint.

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

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 the session cookie obtained from the /login endpoint.

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¶

First Step: Call the /login endpoint with valid credentials to obtain a session cookie:

curl -X POST http://localhost:7860/login \
  -d "username=admin&password=password" \
  -c cookies.txt

Subsequent Requests: Include the session cookie in all authenticated API calls:

curl -X GET http://localhost:7860/api/server_details/all \
  -b cookies.txt

Session Expiration: The session cookie is valid for 8 hours. After expiration, you'll need to login again.

API Summary¶

GET /login: Display login form.
POST /login: Authenticate user and obtain session cookie (required for all authenticated endpoints).
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¶

Login Form¶

Login Submission¶

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¶