Skip to main content

​
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

MethodEndpointDescription
POST/v1/searchSemantic search for MCP servers
POST/v1/invocationsRecord tool invocation outcome

​
Identity (Server-Side Token Management)

MethodEndpointDescription
POST/v1/identity/tokenGet or create MIT for a user
POST/v1/identity/refreshRefresh an expired MIT
POST/v1/identity/revokeRevoke all tokens for a user
POST/v1/identity/sessionsCreate JIT auth session
GET/v1/identity/sessions/{id}Poll auth session status

​
OAuth Proxy (Google APIs)

MethodEndpointDescription
GET/v1/proxy/{provider}/infoCheck if user has connected provider
*/v1/proxy/{provider}/{path}Proxy request to provider API

​
MCP Server Proxy

MethodEndpointDescription
GET/v1/mcp/serverGet MCP server info
POST/v1/mcp/callGeneric JSON-RPC call to server
POST/v1/mcp/tools/listList tools from a server
POST/v1/mcp/tools/callCall 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"
}
StatusMeaning
400Bad request - invalid parameters
401Missing or invalid API key
403Forbidden - missing scope, provider not connected, or token expired
404Resource not found
410Gone - MCP server no longer active
429Rate limited
500Server error
502Bad gateway - MCP server error

​
Error Codes

For 403 responses, check the detail.code field:
CodeMeaning
provider_not_connectedUser hasn’t connected the OAuth provider
token_expiredUser’s OAuth token has expired
invalid_tokenMIT is invalid or expired

​
Rate Limits

TierRequests/min
Free100
Pro1,000
EnterpriseCustom
Rate limit headers are included in responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200