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

# MCP server

> Connect an MCP-compatible AI client to your Grade SDK v1 account.

The Grade MCP server lets an MCP-compatible AI client use your SDK v1 credentials to inspect payouts, wallet activity, creators, campaigns, KYC recipients, and analytics. It runs on your machine over stdio; your API key is supplied through the process environment and is not a tool argument.

## Prerequisites

* Node.js 20 or newer
* A Grade SDK application ID and API key

<Warning>
  Treat your API key like a password. Store it in the MCP client's environment configuration, not in chat messages or tool arguments.
</Warning>

## Connect your client

<Steps>
  <Step title="Open the MCP configuration">
    Open the JSON configuration used by your MCP-compatible client.
  </Step>

  <Step title="Add the Grade server">
    Add the following entry and replace the two placeholder values with the credentials supplied by Grade.

    ```json theme={null}
    {
      "mcpServers": {
        "grade": {
          "command": "npx",
          "args": ["-y", "@usegrade/mcp-server@latest"],
          "env": {
            "GRADE_APPLICATION_ID": "app_...",
            "GRADE_API_KEY": "sk_..."
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Restart the client">
    Restart the AI client so it starts the Grade MCP process. Ask it to get your Grade wallet balance to verify the connection.
  </Step>
</Steps>

Read tools are enabled by default. They cover wallet balances, payouts, transaction and creator payment history, KYC status, campaigns, contracts, media, bonus templates, supported timezones, and standalone analytics.

## Enable write tools

Write tools are not registered unless you explicitly enable them. Add this environment variable to the same `env` object:

```json theme={null}
{
  "GRADE_MCP_ENABLE_WRITES": "true"
}
```

After restarting the client, it can create or change payouts, KYC invites, campaigns, contracts, media, bonus templates, and analytics collections.

<Warning>
  Enabling write tools lets the client make changes to your Grade account. Keep your client's tool-approval prompts enabled. Review the exact recipient, currency, amount, and fee settings before approving a payout.
</Warning>

### Safer payout flow

1. Trigger the payout with `requireConfirmation: true` and a unique `idempotencyKey`.
2. Review the returned payout preview, including the recipient, amount, currency, and platform fee.
3. Confirm the pending payout with a new idempotency key only after the preview is correct.

The payout trigger, confirmation, bulk confirmation, and cancellation tools require an explicit idempotency key. Reuse the same key only when retrying the exact same business operation.

## Optional settings

| Variable | Default | Description |
| - | - | - |
| `GRADE_API_BASE_URL` | `https://infra.usegrade.com/api/email` | Override the Grade API URL for a development or test environment. |
| `GRADE_MCP_TIMEOUT_MS` | `15000` | Per-request timeout in milliseconds. |
| `GRADE_MCP_MAX_RESPONSE_BYTES` | `1000000` | Maximum API response size passed into model context. Narrow the query before increasing it. |
| `GRADE_MCP_ALLOW_INSECURE_HTTP` | `false` | Allow HTTP for a trusted non-local development host. Localhost HTTP works without this setting. |

## API coverage

The MCP server exposes allowlisted JSON endpoints from the public SDK v1 API. It does not accept arbitrary paths or hosts from tool calls.

CSV/PDF exports and invoice downloads are not MCP tools because binary files consume model context without giving the client a reliable place to save them. Use the [payout](/payouts), [transaction](/transactions), and [invoice](/invoices) SDK endpoints for those downloads.

## Troubleshooting

* **Server does not start:** Check that both credential environment variables are present and Node.js is version 20 or newer.
* **`401` response:** Verify the application ID and API key belong to the same active SDK application.
* **`403` response:** If you configured an origin allowlist, confirm your integration policy permits server-to-server requests.
* **Response too large:** Add narrower date, status, search, or pagination filters. Increase `GRADE_MCP_MAX_RESPONSE_BYTES` only when needed.
* **Write tool is missing:** Set `GRADE_MCP_ENABLE_WRITES` to `true`, then restart the client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.