REST API

Base URL

All API endpoints are served under:

https://mcpscoreboard.com/api/v1/

No authentication is required. All endpoints accept GET requests unless otherwise noted.

Rate Limits

The API is rate-limited per IP address. If you exceed the limit, you'll receive a 429 Too Many Requests response. Current limits:

Response Format

All responses are JSON. Paginated endpoints return:

{
  "meta": {
    "total": 24000,
    "page": 1,
    "per_page": 50,
    "total_pages": 480
  },
  "results": [ ... ]
}

Error responses return:

{
  "detail": "Error message here."
}

List Servers

GET /v1/servers/

Paginated list of all scored MCP servers. Supports filtering and sorting.

Query Parameters

Response Fields

Each server in results includes: id, name, description, language, repo_url, current_score, current_grade, score_type, visibility_level, dimensions_scored, dimensions_applicable, dimension scores (schema_quality_score, protocol_score, reliability_score, docs_maintenance_score, security_score, agent_usability_score), uptime_7d, latency_p50, stars_count, is_remote, updated_at.

Get Server

GET /v1/servers/{server_id}/

Full details for a single server by UUID.

Additional Fields

Beyond the list fields: remote_endpoint_url, last_commit_at, latest_version, sources, is_active, first_seen_at.

Score History

GET /v1/servers/{server_id}/history/

Historical scores over time for a server.

Query Parameters

Response

Array of history entries: recorded_at, composite_score, grade, score_type, dimension scores, uptime_7d, latency_p50.

Probe Status

GET /v1/servers/{server_id}/status/

Latest probe result for a server, including reachability, latency, and schema validation.

Response Fields

probed_at, probe_type, is_reachable, connection_ms, initialize_ms, ping_ms, error_message, tools_count, schema_valid.

Ecosystem Summary

GET /v1/scores/summary/

Aggregate statistics across the entire ecosystem. Cached for 5 minutes.

Response Fields

total_servers, scored_servers, remote_servers, average_score, grade_distribution (array of grade/count), language_distribution, score_type_distribution, visibility_distribution.

Install Config

GET /v1/servers/{server_id}/install-config/

Get the install configuration for a server — command, args, env vars, and compatibility info.

Response Fields

server_id, server_name, command, args, env_schema, config_key, transport, remote_url, compatibility, install_notes, source, verified, verification_result.

Installable Servers

GET /v1/servers/installable/

Paginated list of servers that have install configurations.

Query Parameters

Pre-flight

POST /v1/preflight/

Run an instant quality probe against any remote MCP server URL. Results are ephemeral and not stored.

Request Body

{
  "url": "https://your-mcp-server.example.com/sse"
}

Response Fields

is_reachable, connection_ms, initialize_ms, ping_ms, error_message, tools_list_ms, tools_count, schema_valid, schema_issues, error_handling_score, error_handling_details, fuzz_score, fuzz_details, auth_discovery_valid, protocol_score.

cURL Examples

# List top-scored servers
curl "https://mcpscoreboard.com/api/v1/servers/?sort=-score&per_page=10"

# Get a specific server
curl "https://mcpscoreboard.com/api/v1/servers/{server_id}/"

# Ecosystem summary
curl "https://mcpscoreboard.com/api/v1/scores/summary/"

# Search for servers by name
curl "https://mcpscoreboard.com/api/v1/servers/?q=filesystem"

# Filter by grade
curl "https://mcpscoreboard.com/api/v1/servers/?grade=A&sort=-score"

Python

import requests

BASE = "https://mcpscoreboard.com/api/v1"

# List top 10 servers
resp = requests.get(f"{BASE}/servers/", params={"sort": "-score", "per_page": 10})
data = resp.json()

for server in data["results"]:
    print(f"{server['name']}: {server['current_grade']} ({server['current_score']})")

# Ecosystem summary
summary = requests.get(f"{BASE}/scores/summary/").json()
print(f"Total servers: {summary['total_servers']}")
print(f"Average score: {summary['average_score']}")

JavaScript

const BASE = "https://mcpscoreboard.com/api/v1";

// List top 10 servers
const resp = await fetch(`${BASE}/servers/?sort=-score&per_page=10`);
const data = await resp.json();

data.results.forEach(server => {
  console.log(`${server.name}: ${server.current_grade} (${server.current_score})`);
});

// Ecosystem summary
const summary = await fetch(`${BASE}/scores/summary/`).then(r => r.json());
console.log(`Total servers: ${summary.total_servers}`);