> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcprank.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> MCP Rank REST API documentation

# 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:

```bash theme={null}
curl https://api.mcprank.com/v1/health \
  -H "X-API-Key: sk_mcp_rank_..."
```

Get your API key from the [dashboard](https://mcprank.com/dashboard/api-keys).

For proxy requests that access user data, you also need an MCP Identity Token (MIT) in the `Authorization` header:

```bash theme={null}
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:

```json theme={null}
{
  "data": { ... },
  "metadata": {
    "request_id": "req_abc123",
    "latency_ms": 45
  }
}
```

## Errors

Errors return appropriate HTTP status codes:

```json theme={null}
{
  "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
```