Registry API

The MCP Registry API provides endpoints for managing MCP server registrations.

Base URL

http://localhost:8080

Authentication

Scanner operations require an API key in the X-API-Key header:

curl -H "X-API-Key: your-api-key" http://localhost:8080/mcp-servers

Endpoints Overview

Endpoint	Method	Description
/mcp-servers	GET	List all MCP servers
/mcp-servers	POST	Register a new server
/mcp-servers/:id	GET	Get server by ID
/mcp-servers/:id	PUT	Update server
/mcp-servers/:id	DELETE	Remove server
/scanners	GET	List scanners
/scanners	POST	Register scanner
/scanners/:id	GET	Get scanner by ID
/health	GET	Health check
/ready	GET	Readiness check

MCP Servers

GET /mcp-servers

List all registered MCP servers.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status (active, unhealthy, unknown)
capability	string	Filter by capability/tool name
scanner_id	string	Filter by scanner

Response:

{
  "servers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-search",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-web-search"],
      "capabilities": {
        "tools": [
          {
            "name": "search_web",
            "description": "Search the web",
            "input_schema": {
              "type": "object",
              "properties": {
                "query": {"type": "string"}
              }
            }
          }
        ],
        "resources": [],
        "prompts": []
      },
      "status": "active",
      "last_verified": "2024-01-15T10:00:00Z",
      "scanner_id": "scanner-uuid"
    }
  ]
}

POST /mcp-servers

Register a new MCP server.

Headers:

X-API-Key: scanner-api-key
Content-Type: application/json

Request Body:

{
  "name": "my-mcp-server",
  "command": "node",
  "args": ["./server.js"],
  "env": {
    "API_KEY": "secret"
  },
  "capabilities": {
    "tools": [
      {
        "name": "my_tool",
        "description": "Does something useful",
        "input_schema": {
          "type": "object",
          "properties": {
            "input": {"type": "string"}
          },
          "required": ["input"]
        }
      }
    ]
  }
}

Response:

{
  "id": "generated-uuid",
  "name": "my-mcp-server",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Status Codes:

Code	Description
201	Server registered
400	Invalid request
401	Invalid API key
409	Server already exists

GET /mcp-servers/:id

Get a specific MCP server.

Response: Server object

Status Codes:

Code	Description
200	Server found
404	Server not found

PUT /mcp-servers/:id

Update an MCP server.

Headers:

X-API-Key: scanner-api-key

Request Body: Same as POST

Status Codes:

Code	Description
200	Server updated
401	Invalid API key
404	Server not found

DELETE /mcp-servers/:id

Remove an MCP server.

Headers:

X-API-Key: scanner-api-key

Status Codes:

Code	Description
204	Server removed
401	Invalid API key
404	Server not found

Scanners

GET /scanners

List all registered scanners.

Response:

{
  "scanners": [
    {
      "id": "scanner-uuid",
      "agent_id": "scanner-001",
      "name": "Production Scanner",
      "last_seen": "2024-01-15T10:00:00Z",
      "is_active": true,
      "servers_count": 15
    }
  ]
}

POST /scanners

Register a new scanner.

Request Body:

{
  "agent_id": "scanner-001",
  "name": "My Scanner",
  "api_key": "secret-api-key"
}

Response:

{
  "id": "generated-uuid",
  "agent_id": "scanner-001",
  "name": "My Scanner",
  "created_at": "2024-01-15T10:00:00Z"
}

Status Codes:

Code	Description
201	Scanner registered
400	Invalid request
409	Agent ID already exists

GET /scanners/:id

Get a specific scanner.

Response: Scanner object with statistics

Health Checks

GET /health

Basic health check.

Response:

{
  "status": "healthy",
  "database": "connected"
}

GET /ready

Readiness check.

Response:

{
  "status": "ready",
  "database": "connected",
  "servers_count": 25,
  "scanners_count": 3
}

Error Responses

All error responses follow this format:

{
  "error": "NotFound",
  "message": "MCP server not found",
  "details": {
    "id": "non-existent-id"
  }
}

Webhooks

The registry can send webhooks for server status changes:

{
  "event": "server.status_changed",
  "server_id": "uuid",
  "old_status": "active",
  "new_status": "unhealthy",
  "timestamp": "2024-01-15T10:00:00Z"
}

Configure webhooks via environment variable:

WEBHOOK_URL=https://your-app.com/webhooks/mcp-registry

OpenAPI Specification

The full OpenAPI specification is available at:

• /openapi.json - JSON format
• /openapi.yaml - YAML format

Interactive API explorer coming soon with OpenAPI integration.