API Documentation

Search, score, and compare MCP servers. 10 free queries per day. Unlimited with an API key.

Base URL

https://pulrix.dev/api/v1

Authentication

Free tier: 10 queries/day by IP. No auth needed.

Authenticated: unlimited queries. Pass your API key as a Bearer token:

Authorization: Bearer plx_your_api_key_here

Rate Limiting

Anonymous requests include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Returns 429 when exceeded.

Endpoints

GET/api/v1/search

Search for MCP servers by keyword. Returns servers with their latest grade and score.

Parameters

qstringrequiredSearch query (max 200 chars)

gradestringFilter by grade (A+, A, B, C, D, F)

limitnumberResults per page (default 20, max 50)

offsetnumberPagination offset (default 0)

Example

curl "https://pulrix.dev/api/v1/search?q=postgres&limit=5"

Response

{
  "query": "postgres",
  "count": 5,
  "total": 5,
  "limit": 5,
  "offset": 0,
  "servers": [
    {
      "id": "crystaldba/postgres-mcp",
      "name": "postgres-mcp",
      "grade": "A",
      "score": 82,
      "description": "All-in-one MCP server for PostgreSQL",
      "repo_url": "https://github.com/crystaldba/postgres-mcp",
      "last_scored": "2026-03-20T14:30:00.000Z"
    }
  ]
}

GET/api/v1/servers/:id

Get detailed information about a specific server, including full score breakdown and history.

Parameters

idstringrequiredServer ID (URL path parameter)

Example

curl "https://pulrix.dev/api/v1/servers/crystaldba%2Fpostgres-mcp"

Response

{
  "server": {
    "id": "crystaldba/postgres-mcp",
    "name": "postgres-mcp",
    "description": "All-in-one MCP server for PostgreSQL",
    "repo_url": "https://github.com/crystaldba/postgres-mcp",
    "npm_package": "@crystaldba/postgres-mcp",
    "source": "awesome-list",
    "first_seen": "2026-03-01T00:00:00.000Z"
  },
  "score": {
    "grade": "A",
    "total": 82,
    "scored_at": "2026-03-20T14:30:00.000Z",
    "quality": {
      "signals": {
        "schema_valid": { "points": 15, "max": 15 },
        "readme": { "points": 6, "max": 6 },
        "tests": { "points": 6, "max": 6 },
        "typescript": { "points": 6, "max": 6 },
        "license": { "points": 3, "max": 3 },
        "stars": { "points": 5, "max": 6 },
        "activity": { "points": 10, "max": 10 },
        "issues": { "points": 3, "max": 3 },
        "cves": { "points": 5, "max": 5 }
      }
    },
    "security": {
      "score": 40,
      "max": 40,
      "findings_count": 0,
      "vendors": {
        "virustotal": { "malicious": 0, "total_engines": 72 },
        "osv": { "total_vulns": 0 },
        "github_advisories": { "total": 0 }
      }
    }
  },
  "history": [
    { "grade": "A", "total": 82, "scored_at": "2026-03-20T..." },
    { "grade": "B", "total": 78, "scored_at": "2026-03-13T..." }
  ]
}

GET/api/v1/top

Get top-scoring MCP servers, optionally filtered by category or grade.

Parameters

categorystringFilter by category keyword (default: all)

gradestringFilter by minimum grade

limitnumberResults to return (default 25, max 50)

Example

curl "https://pulrix.dev/api/v1/top?grade=A&limit=10"

Response

{
  "category": "all",
  "count": 10,
  "servers": [
    {
      "id": "modelcontextprotocol/servers",
      "name": "servers",
      "grade": "A+",
      "score": 94,
      "description": "Official MCP reference servers",
      "repo_url": "https://github.com/modelcontextprotocol/servers",
      "last_scored": "2026-03-20T14:30:00.000Z"
    }
  ]
}

GET/api/v1/compare

Compare up to 5 servers side by side. Returns a recommendation for the best option.

Parameters

idsstringrequiredComma-separated server IDs (max 5)

Example

curl "https://pulrix.dev/api/v1/compare?ids=server-a,server-b,server-c"

Response

{
  "servers": [
    { "id": "server-a", "name": "Server A", "grade": "A", "score": 85 },
    { "id": "server-b", "name": "Server B", "grade": "B", "score": 72 },
    { "id": "server-c", "name": "Server C", "grade": null, "score": null, "error": "Not found" }
  ],
  "recommendation": "server-a",
  "reason": "Highest composite score (85/100, grade A)"
}

GET/api/v1/stats

Get aggregate statistics about the Pulrix index.

Example

curl "https://pulrix.dev/api/v1/stats"

Response

{
  "total_servers": 17432,
  "scored_servers": 14891,
  "grade_distribution": {
    "A+": 142, "A": 891, "B": 2341,
    "C": 4521, "D": 3102, "F": 3894
  },
  "last_crawl": null,
  "last_score_run": null
}

POST/api/v1/checkAPI key required

Request an on-demand security check for a specific MCP server. Coming in v0.2.

Parameters

urlstringrequiredGitHub repo URL or npm package name

Example

curl -X POST "https://pulrix.dev/api/v1/check" \
  -H "Authorization: Bearer plx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo"}'

Response

{
  "error": "On-demand check coming in v0.2",
  "code": "NOT_IMPLEMENTED"
}

CLI

The Pulrix CLI wraps the API. No installation needed.

Search

npx pulrix search "postgres"

Server details

npx pulrix info github:owner/repo

Compare

npx pulrix compare server-a server-b

MCP Server

Let your AI agent search for and evaluate its own tools.

{
  "mcpServers": {
    "pulrix": {
      "command": "npx",
      "args": ["-y", "pulrix", "mcp"]
    }
  }
}

Add your API key via PULRIX_API_KEY env var for unlimited queries.

Error Codes

Status	Meaning
200	Success
400	Bad request (missing or invalid parameters)
401	Unauthorized (API key required for this endpoint)
404	Server not found
429	Rate limit exceeded (10/day free tier)
500	Server error
501	Not implemented (feature coming soon)

Questions? Open an issue on GitHub or email hello@pulrix.dev. See how scores are calculated on the methodology page.