Skip to main content

MCPs API

Endpoints for managing and interacting with MCPs.

List MCPs​

Get all MCPs in your organization.

GET /v1/mcps

Query Parameters​

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 20, max: 100)
statusstringFilter: active, inactive, all
healthstringFilter: healthy, unhealthy

Response​

{
  "success": true,
  "data": [
    {
      "id": "mcp_123",
      "name": "Weather API",
      "endpoint_url": "https://weather-mcp.example.com",
      "description": "Weather data and forecasts",
      "status": "active",
      "health": "healthy",
      "created_at": "2024-01-15T10:30:00Z",
      "last_active": "2024-01-20T15:45:00Z",
      "request_count": 8000
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 3,
    "total_pages": 1
  }
}

Get MCP Details​

Get detailed information about a specific MCP.

GET /v1/mcps/{mcp_id}

Response​

{
  "success": true,
  "data": {
    "id": "mcp_123",
    "name": "Weather API",
    "endpoint_url": "https://weather-mcp.example.com",
    "description": "Weather data and forecasts",
    "status": "active",
    "health": "healthy",
    "health_checked_at": "2024-01-20T15:40:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-18T12:00:00Z",
    "last_active": "2024-01-20T15:45:00Z",
    "stats": {
      "total_requests": 8000,
      "requests_today": 450,
      "error_rate": 0.02,
      "avg_latency_ms": 125
    },
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or coordinates"
            }
          },
          "required": ["location"]
        }
      },
      {
        "name": "get_forecast",
        "description": "Get weather forecast",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": { "type": "string" },
            "days": { "type": "integer", "default": 5 }
          },
          "required": ["location"]
        }
      }
    ]
  }
}

Invoke MCP Tool​

Call a tool on an MCP.

POST /v1/mcp/invoke

Request Body​

{
  "mcp_id": "mcp_123",
  "tool": "get_weather",
  "arguments": {
    "location": "San Francisco, CA"
  }
}

Response​

{
  "success": true,
  "data": {
    "result": {
      "location": "San Francisco, CA",
      "temperature": 65,
      "unit": "fahrenheit",
      "conditions": "Partly cloudy",
      "humidity": 72
    },
    "metadata": {
      "mcp_id": "mcp_123",
      "tool": "get_weather",
      "latency_ms": 125,
      "timestamp": "2024-01-20T15:45:00Z"
    }
  }
}

Read MCP Resources​

Read resources exposed by an MCP.

POST /v1/mcp/resources

Request Body​

{
  "mcp_id": "mcp_123",
  "uri": "weather://locations"
}

Response​

{
  "success": true,
  "data": {
    "contents": [
      {
        "uri": "weather://locations/sf",
        "name": "San Francisco",
        "mimeType": "application/json"
      },
      {
        "uri": "weather://locations/nyc",
        "name": "New York City",
        "mimeType": "application/json"
      }
    ]
  }
}

Create MCP​

Register a new MCP (Admin/Owner only).

POST /v1/mcps

Request Body​

{
  "name": "Weather API",
  "endpoint_url": "https://weather-mcp.example.com",
  "description": "Weather data and forecasts",
  "auth_type": "bearer",
  "auth_token": "secret_token"
}

Response​

{
  "success": true,
  "data": {
    "id": "mcp_789",
    "name": "Weather API",
    "endpoint_url": "https://weather-mcp.example.com",
    "description": "Weather data and forecasts",
    "status": "active",
    "health": "unknown",
    "created_at": "2024-01-20T16:00:00Z"
  }
}

Update MCP​

Update MCP configuration (Admin/Owner only).

PATCH /v1/mcps/{mcp_id}

Request Body​

{
  "name": "Updated Weather API",
  "description": "Updated description",
  "status": "active"
}

Response​

{
  "success": true,
  "data": {
    "id": "mcp_123",
    "name": "Updated Weather API",
    "description": "Updated description",
    "status": "active",
    "updated_at": "2024-01-20T16:00:00Z"
  }
}

Delete MCP​

Remove an MCP (Admin/Owner only).

DELETE /v1/mcps/{mcp_id}

Response​

{
  "success": true,
  "data": {
    "deleted": true,
    "mcp_id": "mcp_123"
  }
}

Test MCP Connection​

Test connectivity to an MCP.

POST /v1/mcps/{mcp_id}/test

Response​

{
  "success": true,
  "data": {
    "reachable": true,
    "latency_ms": 95,
    "protocol_version": "2024-11-05",
    "tools_count": 5,
    "resources_count": 2
  }
}

Errors​

404 Not Found​

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "MCP not found"
  }
}

502 Bad Gateway​

{
  "success": false,
  "error": {
    "code": "mcp_unreachable",
    "message": "Could not connect to MCP server"
  }
}

504 Gateway Timeout​

{
  "success": false,
  "error": {
    "code": "mcp_timeout",
    "message": "MCP server did not respond in time"
  }
}