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¶
- API Categories
- Authentication Schemes
- A2A Agent Management APIs
- Anthropic MCP Registry API v0
- Internal Server Management APIs
- Authentication & Login APIs
- Health Monitoring APIs
- Discovery & Well-Known Endpoints
- Utility Endpoints
- Response Codes & Error Handling
- OpenAPI Specifications
API Categories¶
| Category | Count | Auth Method | Purpose |
|---|---|---|---|
| A2A Agent Management | 8 | JWT Bearer Token | Agent registration, discovery, and management |
| Anthropic Registry API v0 (Servers) | 3 | JWT Bearer Token | Standard MCP server discovery via Anthropic API spec |
| Internal Server Management (UI) | 10 | Session Cookie | Dashboard and service management |
| Internal Server Management (Admin) | 12 | HTTP Basic Auth | Administrative operations and group management |
| Authentication & Login | 7 | OAuth2 + Session | User authentication and provider management |
| Health Monitoring | 3 | Session Cookie / None | Real-time health updates and statistics |
| Discovery | 1 | None (Public) | Public MCP server discovery |
| Utility | 2 | Session Cookie / Public | Current user info and service health |
| TOTAL | 46 | Multiple | Full registry functionality |
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
/validateendpoint 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/api/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_sessioncookie - Browser automatically includes cookie in subsequent requests
- Registry validates cookie against auth-server
Example:
3. HTTP Basic Auth¶
Used by: Internal Admin Endpoints
How it works:
- Credentials:
ADMIN_USER:ADMIN_PASSWORDfrom environment - Sent in
Authorization: Basic <base64>header - Used for internal mcpgw-server operations
Example:
4. Public (No Authentication)¶
Used by: Discovery endpoints, login page, OAuth2 providers list
Endpoints:
GET /.well-known/mcp-serversGET /api/auth/loginGET /api/auth/providersGET /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 exists422 Unprocessable Entity- Validation error (invalid JSON, missing fields)403 Forbidden- User lackspublish_agentpermission
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 stringenabled_only(optional, boolean, default: false) - Show only enabled agentsvisibility(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 exist403 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 exist403 Forbidden- User lacks modify permission422 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 exist403 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
Error Codes:
404 Not Found- Agent doesn't exist403 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:
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 query500 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.1/servers
Purpose: List all MCP servers with cursor-based pagination
Query Parameters:
cursor(optional, string) - Pagination cursor from previous responselimit(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.1/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.1/servers/{serverName:path}/versions/{version}
Purpose: Get detailed information about a specific server version
Path Parameters:
serverName- URL-encoded server nameversion- Version string orlatest
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 exist403 Forbidden- User lacks toggle permission500 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 exists403 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 orall
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 orall
Response: 200 OK
Error Codes:
404 Not Found- Service not found400 Bad Request- Service disabled403 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 namegroup_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_namedescription(optional)create_in_idp(optional)
Response: 200 OK
19. Delete Group¶
Endpoint: POST /api/internal/delete-group
Form Parameters:
group_namedelete_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 user500 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:
usernamepassword
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
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
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
Response Codes & Error Handling¶
Success Responses¶
| Code | Meaning | Use Case |
|---|---|---|
200 OK | Successful GET/POST | Data retrieval, updates |
201 Created | Resource created | Agent/server registration |
204 No Content | Successful deletion | DELETE operations |
303 See Other | Redirect after form | Form submissions (POST) |
Client Error Responses¶
| Code | Meaning | Example |
|---|---|---|
400 Bad Request | Invalid input | Missing required fields, invalid JSON |
401 Unauthorized | Authentication failed | Missing/invalid JWT token |
403 Forbidden | Permission denied | User lacks required scope |
404 Not Found | Resource doesn't exist | Agent/server not found |
409 Conflict | Resource conflict | Agent path already registered |
422 Unprocessable Entity | Validation error | Invalid field values |
Server Error Responses¶
| Code | Meaning | Example |
|---|---|---|
500 Internal Server Error | Server error | Exception during processing |
502 Bad Gateway | Upstream error | Auth server unreachable |
503 Service Unavailable | Service down | Database unavailable |
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:
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¶
- 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
-
API Documentation: Import into Postman, Insomnia, or other API tools
-
Validation: Use
openapi-spec-validatorto validate the spec
Summary Table¶
| Category | Endpoints | Auth | Purpose |
|---|---|---|---|
| A2A Agents | 8 | JWT Bearer | Agent lifecycle management |
| Anthropic v0 (Servers) | 3 | JWT Bearer | Standard server discovery |
| Anthropic v0 (Agents) | 3 | JWT Bearer | Standard agent discovery |
| UI Management | 10 | Session Cookie | Dashboard operations |
| Admin Operations | 12 | HTTP Basic Auth | Administrative tasks |
| Authentication | 7 | OAuth2/Session | User login/logout |
| Health Monitoring | 3 | Session/None | Real-time status |
| Discovery | 1 | None | Public server discovery |
| Utility | 2 | Session/None | Helper endpoints |
| TOTAL | 49 | Multiple | Full system coverage |
Quick Reference by Use Case¶
I want to register an agent¶
- Endpoint:
POST /api/agents/register - Auth: JWT Bearer Token with
publish_agentscope - 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.1/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¶
| Date | Version | Changes |
|---|---|---|
| 2025-11-01 | 1.0 | Initial API reference documentation, 49 endpoints cataloged |