API Overview

The MCP Rank API provides programmatic access to:

Search: Find relevant MCP servers via semantic search
Identity: Server-side token management for user authentication
OAuth Proxy: Make Google API calls on behalf of users
MCP Proxy: Call MCP server tools through MCP Rank

Base URL

https://api.mcprank.com

Authentication

All requests require an API key in the X-API-Key header:

curl https://api.mcprank.com/v1/health \
  -H "X-API-Key: sk_mcp_rank_..."

Get your API key from the dashboard. For proxy requests that access user data, you also need an MCP Identity Token (MIT) in the Authorization header:

curl https://api.mcprank.com/v1/proxy/google/gmail/v1/users/me/profile \
  -H "X-API-Key: sk_mcp_rank_..." \
  -H "Authorization: Bearer <MIT>"

Endpoints

Search

Method	Endpoint	Description
POST	`/v1/search`	Semantic search for MCP servers
POST	`/v1/invocations`	Record tool invocation outcome

Identity (Server-Side Token Management)

Method	Endpoint	Description
POST	`/v1/identity/token`	Get or create MIT for a user
POST	`/v1/identity/refresh`	Refresh an expired MIT
POST	`/v1/identity/revoke`	Revoke all tokens for a user
POST	`/v1/identity/sessions`	Create JIT auth session
GET	`/v1/identity/sessions/{id}`	Poll auth session status

OAuth Proxy (Google APIs)

Method	Endpoint	Description
GET	`/v1/proxy/{provider}/info`	Check if user has connected provider
*	`/v1/proxy/{provider}/{path}`	Proxy request to provider API

MCP Server Proxy

Method	Endpoint	Description
GET	`/v1/mcp/server`	Get MCP server info
POST	`/v1/mcp/call`	Generic JSON-RPC call to server
POST	`/v1/mcp/tools/list`	List tools from a server
POST	`/v1/mcp/tools/call`	Call a specific tool

Response Format

All responses are JSON:

{
  "data": { ... },
  "metadata": {
    "request_id": "req_abc123",
    "latency_ms": 45
  }
}

Errors

Errors return appropriate HTTP status codes:

{
  "detail": "Invalid API key"
}

Status	Meaning
400	Bad request - invalid parameters
401	Missing or invalid API key
403	Forbidden - missing scope, provider not connected, or token expired
404	Resource not found
410	Gone - MCP server no longer active
429	Rate limited
500	Server error
502	Bad gateway - MCP server error

Error Codes

For 403 responses, check the detail.code field:

Code	Meaning
`provider_not_connected`	User hasn’t connected the OAuth provider
`token_expired`	User’s OAuth token has expired
`invalid_token`	MIT is invalid or expired

Rate Limits

Tier	Requests/min
Free	100
Pro	1,000
Enterprise	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

​API Overview

​Base URL

​Authentication

​Endpoints

​Search

​Identity (Server-Side Token Management)

​OAuth Proxy (Google APIs)

​MCP Server Proxy

​Response Format

​Errors

​Error Codes

​Rate Limits