Reference

Public API

MCP Playground exposes a free, CORS-enabled REST API. Use it to check server health in CI, list available tools programmatically, or build your own integrations on top of the MCP registry.

Base URL

https://mcpplayground.tech/api/v1

Rate limits

/health — 30 requests per minute per IP

/inspect — 10 requests per minute per IP

/registry/servers — 20 requests per minute per IP

/lint — 10 requests per minute per IP

Exceeding limits returns 429 with a RATE_LIMITED error code.

GET/api/v1/health

Lightweight health check. Pings an MCP server with a minimal initialize request and returns status and latency.

Query parameters

url

stringrequired

The MCP server URL to check. Supports http(s):// and ws(s):// schemes.

Example request

bash

curl "https://mcpplayground.tech/api/v1/health?url=https://mcp.deepwiki.com/mcp"

Example response

json

{
  "ok": true,
  "status": "up",
  "latencyMs": 342,
  "statusCode": 200,
  "url": "https://mcp.deepwiki.com/mcp",
  "_meta": {
    "api": "v1",
    "docs": "https://mcpplayground.tech/docs/api"
  }
}

Status values

"up" — Server responded successfully

"auth_required" — Server returned 401 or 403

"down" — Server unreachable or returned 5xx

GET/api/v1/inspect

Connect to an MCP server and return all tools, resources, and prompts with their full JSON Schemas.

Query parameters

url

stringrequired

The MCP server URL to inspect. Supports http(s):// and ws(s):// schemes.

Example request

bash

curl "https://mcpplayground.tech/api/v1/inspect?url=https://mcp.deepwiki.com/mcp"

Example response (truncated)

json

{
  "ok": true,
  "url": "https://mcp.deepwiki.com/mcp",
  "serverInfo": {
    "name": "deepwiki",
    "version": "1.0.0"
  },
  "capabilities": {
    "tools": true,
    "resources": false,
    "prompts": false
  },
  "transport": "streamable-http",
  "connectionTimeMs": 523,
  "tools": [
    {
      "name": "ask_question",
      "description": "Ask a question about a GitHub repository",
      "inputSchema": {
        "type": "object",
        "properties": {
          "...": "..."
        }
      }
    }
  ],
  "resources": [],
  "prompts": [],
  "_meta": {
    "api": "v1",
    "docs": "https://mcpplayground.tech/docs/api"
  }
}

Note: This endpoint does not support auth headers. For servers that require authentication, use the Playground UI or POST /api/mcp/inspect with headers in the request body.

GET/api/v1/registry/servers

Browse and search the official MCP server registry. Returns server metadata, package info, and remote endpoint URLs.

Query parameters

id

string

Fetch a single server by registry name (e.g. deepwiki/deepwiki). Returns a single server object instead of a list.

q

string

Search by name, description, or ID. Case-insensitive substring match.

remote

boolean

Set to true to only return servers that have a remote HTTP endpoint URL.

limit

number

Results per page. Default: 50, max: 200.

offset

number

Skip N results for pagination. Default: 0.

Example — list all servers with a remote endpoint

bash

curl "https://mcpplayground.tech/api/v1/registry/servers?remote=true&limit=10"

Example — search for a server

bash

curl "https://mcpplayground.tech/api/v1/registry/servers?q=filesystem&limit=5"

Example — fetch a single server by ID

bash

curl "https://mcpplayground.tech/api/v1/registry/servers?id=deepwiki/deepwiki"

Example response (list)

json

{
  "ok": true,
  "servers": [
    {
      "id": "deepwiki/deepwiki",
      "name": "DeepWiki",
      "description": "Query any GitHub repository docs",
      "remoteUrl": "https://mcp.deepwiki.com/mcp",
      "packages": [
        {
          "registry_name": "npm",
          "name": "deepwiki"
        }
      ]
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  },
  "_meta": {
    "api": "v1",
    "docs": "https://mcpplayground.tech/docs/api"
  }
}

Error format

All error responses follow the same shape:

json

{
  "ok": false,
  "error": "Human-readable error message.",
  "code": "ERROR_CODE",
  "_meta": {
    "api": "v1",
    "docs": "https://mcpplayground.tech/docs/api"
  }
}

Error codes

MISSING_PARAM400A required query parameter is missing.

INVALID_URL400The URL is malformed or points to a private/local address.

UNAUTHORIZED401The server requires authentication.

NOT_FOUND404The requested server was not found in the registry.

TIMEOUT408The server did not respond within the timeout period.

RATE_LIMITED429Too many requests from your IP.

CONNECTION_FAILED502Could not establish a connection to the server.

REGISTRY_ERROR502Failed to fetch data from the upstream MCP registry.

INTERNAL_ERROR500An unexpected server-side error.

Usage examples

CI health check (GitHub Actions)

yaml

- name: Check MCP server health
  run: |
    STATUS=$(curl -s "https://mcpplayground.tech/api/v1/health?url=${{ env.MCP_SERVER_URL }}" | jq -r '.status')
    if [ "$STATUS" != "up" ]; then
      echo "MCP server is $STATUS"
      exit 1
    fi

List all tools for a server (JavaScript)

javascript

const res = await fetch(
  "https://mcpplayground.tech/api/v1/inspect?url=https://mcp.deepwiki.com/mcp"
);
const { tools } = await res.json();
console.log(tools.map(t => t.name));

Find servers with remote endpoints (Python)

python

import requests

res = requests.get("https://mcpplayground.tech/api/v1/registry/servers", params={
    "remote": "true",
    "limit": 20,
})
for server in res.json()["servers"]:
    print(f"{server['name']}: {server['remoteUrl']}")

{ "ok": true, "status": "up", "latencyMs": 342, "statusCode": 200, "url": "https://mcp.deepwiki.com/mcp", "_meta": { "api": "v1", "docs": "https://mcpplayground.tech/docs/api" } }

{ "ok": true, "url": "https://mcp.deepwiki.com/mcp", "serverInfo": { "name": "deepwiki", "version": "1.0.0" }, "capabilities": { "tools": true, "resources": false, "prompts": false }, "transport": "streamable-http", "connectionTimeMs": 523, "tools": [ { "name": "ask_question", "description": "Ask a question about a GitHub repository", "inputSchema": { "type": "object", "properties": { "...": "..." } } } ], "resources": [], "prompts": [], "_meta": { "api": "v1", "docs": "https://mcpplayground.tech/docs/api" } }

{ "ok": true, "servers": [ { "id": "deepwiki/deepwiki", "name": "DeepWiki", "description": "Query any GitHub repository docs", "remoteUrl": "https://mcp.deepwiki.com/mcp", "packages": [ { "registry_name": "npm", "name": "deepwiki" } ] } ], "pagination": { "total": 156, "limit": 10, "offset": 0, "hasMore": true }, "_meta": { "api": "v1", "docs": "https://mcpplayground.tech/docs/api" } }

Error format

All error responses follow the same shape:

json

{
  "ok": false,
  "error": "Human-readable error message.",
  "code": "ERROR_CODE",
  "_meta": {
    "api": "v1",
    "docs": "https://mcpplayground.tech/docs/api"
  }
}

Error codes

MISSING_PARAM400A required query parameter is missing.

INVALID_URL400The URL is malformed or points to a private/local address.

UNAUTHORIZED401The server requires authentication.

NOT_FOUND404The requested server was not found in the registry.

TIMEOUT408The server did not respond within the timeout period.

RATE_LIMITED429Too many requests from your IP.

CONNECTION_FAILED502Could not establish a connection to the server.

REGISTRY_ERROR502Failed to fetch data from the upstream MCP registry.

INTERNAL_ERROR500An unexpected server-side error.

Usage examples

CI health check (GitHub Actions)

yaml

- name: Check MCP server health
  run: |
    STATUS=$(curl -s "https://mcpplayground.tech/api/v1/health?url=${{ env.MCP_SERVER_URL }}" | jq -r '.status')
    if [ "$STATUS" != "up" ]; then
      echo "MCP server is $STATUS"
      exit 1
    fi

List all tools for a server (JavaScript)

javascript

const res = await fetch(
  "https://mcpplayground.tech/api/v1/inspect?url=https://mcp.deepwiki.com/mcp"
);
const { tools } = await res.json();
console.log(tools.map(t => t.name));

Find servers with remote endpoints (Python)

python

import requests

res = requests.get("https://mcpplayground.tech/api/v1/registry/servers", params={
    "remote": "true",
    "limit": 20,
})
for server in res.json()["servers"]:
    print(f"{server['name']}: {server['remoteUrl']}")