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

# Proxy Request

> Proxy requests to OAuth provider APIs

## Overview

The proxy endpoint forwards requests to OAuth provider APIs (e.g., Google) using the user's stored OAuth credentials. This allows your application to access provider APIs without ever handling the user's OAuth tokens directly.

**Supported Methods:** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`

## Path Parameters

<ParamField path="provider" type="string" required>
  OAuth provider name. Currently supported: `google`
</ParamField>

<ParamField path="path" type="string" required>
  The API path to call on the provider. This is appended to the provider's base URL.

  For Google, the base URL is `https://www.googleapis.com/`, so:

  * `gmail/v1/users/me/messages` becomes `https://www.googleapis.com/gmail/v1/users/me/messages`
  * `calendar/v3/calendars/primary/events` becomes `https://www.googleapis.com/calendar/v3/calendars/primary/events`
</ParamField>

## Headers

<ParamField header="X-API-Key" type="string" required>
  Your MCP Rank API key
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer {mcp_identity_access_token}`
</ParamField>

## Request Body

For `POST`, `PUT`, and `PATCH` requests, the request body is forwarded as-is to the provider API. Use the appropriate `Content-Type` header (typically `application/json`).

## Response

The response from the provider API is returned as-is, including:

* Status code
* Response headers (except internal headers)
* Response body

<RequestExample>
  ```bash cURL - Get Gmail Messages theme={null}
  curl "https://api.mcprank.com/v1/proxy/google/gmail/v1/users/me/messages?maxResults=10" \
    -H "X-API-Key: your-api-key" \
    -H "Authorization: Bearer your-access-token"
  ```

  ```bash cURL - Send Email theme={null}
  curl -X POST "https://api.mcprank.com/v1/proxy/google/gmail/v1/users/me/messages/send" \
    -H "X-API-Key: your-api-key" \
    -H "Authorization: Bearer your-access-token" \
    -H "Content-Type: application/json" \
    -d '{
      "raw": "base64-encoded-email-content"
    }'
  ```

  ```python Python - Gmail theme={null}
  from mcp_rank import MCPRank

  client = MCPRank(api_key="your-api-key")
  client.set_user_token(access_token, refresh_token)

  # Get recent emails
  messages = await client.proxy_get(
      "google",
      "gmail/v1/users/me/messages",
      params={"maxResults": 10}
  )

  # Get a specific message
  message = await client.proxy_get(
      "google",
      f"gmail/v1/users/me/messages/{message_id}"
  )
  ```

  ```python Python - Calendar theme={null}
  # List calendar events
  events = await client.proxy_get(
      "google",
      "calendar/v3/calendars/primary/events",
      params={"maxResults": 10}
  )

  # Create a calendar event
  new_event = await client.proxy_post(
      "google",
      "calendar/v3/calendars/primary/events",
      json={
          "summary": "Team Meeting",
          "start": {"dateTime": "2024-01-15T10:00:00Z"},
          "end": {"dateTime": "2024-01-15T11:00:00Z"}
      }
  )
  ```

  ```typescript TypeScript theme={null}
  // Get Gmail messages
  const response = await fetch(
    "https://api.mcprank.com/v1/proxy/google/gmail/v1/users/me/messages?maxResults=10",
    {
      headers: {
        "X-API-Key": "your-api-key",
        "Authorization": `Bearer ${accessToken}`,
      },
    }
  );

  const messages = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Gmail Messages Response theme={null}
  {
    "messages": [
      {
        "id": "18d1234567890abc",
        "threadId": "18d1234567890abc"
      },
      {
        "id": "18d0987654321def",
        "threadId": "18d0987654321def"
      }
    ],
    "resultSizeEstimate": 150
  }
  ```

  ```json Calendar Events Response theme={null}
  {
    "kind": "calendar#events",
    "items": [
      {
        "id": "event123",
        "summary": "Team Meeting",
        "start": {
          "dateTime": "2024-01-15T10:00:00Z"
        },
        "end": {
          "dateTime": "2024-01-15T11:00:00Z"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Google API Examples

### Gmail

| Operation     | Method | Path                              |
| ------------- | ------ | --------------------------------- |
| List messages | GET    | `gmail/v1/users/me/messages`      |
| Get message   | GET    | `gmail/v1/users/me/messages/{id}` |
| Send message  | POST   | `gmail/v1/users/me/messages/send` |
| List labels   | GET    | `gmail/v1/users/me/labels`        |
| Get profile   | GET    | `gmail/v1/users/me/profile`       |

### Calendar

| Operation      | Method | Path                                        |
| -------------- | ------ | ------------------------------------------- |
| List events    | GET    | `calendar/v3/calendars/primary/events`      |
| Create event   | POST   | `calendar/v3/calendars/primary/events`      |
| Update event   | PUT    | `calendar/v3/calendars/primary/events/{id}` |
| Delete event   | DELETE | `calendar/v3/calendars/primary/events/{id}` |
| List calendars | GET    | `calendar/v3/users/me/calendarList`         |

### Drive

| Operation   | Method | Path                  |
| ----------- | ------ | --------------------- |
| List files  | GET    | `drive/v3/files`      |
| Get file    | GET    | `drive/v3/files/{id}` |
| Create file | POST   | `drive/v3/files`      |
| Update file | PATCH  | `drive/v3/files/{id}` |
| Delete file | DELETE | `drive/v3/files/{id}` |

## Error Responses

| Status Code | Description                                |
| ----------- | ------------------------------------------ |
| 400         | Unsupported provider                       |
| 401         | Missing or invalid API key or access token |
| 403         | User has not connected this provider       |
| 413         | Request body too large (max 10MB)          |
| 429         | Rate limit exceeded                        |
| 502         | Failed to connect to provider              |
| 504         | Provider request timed out                 |

<Warning>
  Provider API errors (4xx, 5xx) are passed through as-is. Check the response body for provider-specific error details.
</Warning>

## Security

* Your application never sees the user's OAuth tokens
* Tokens are stored encrypted and managed by MCP Rank
* Tokens are automatically refreshed when they expire
* All proxy requests are logged for audit purposes