All documentation
Documentation
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
Connect your client
-
Open the MCP configuration
Open the JSON configuration used by your MCP-compatible client.
-
Add the Grade server
Add the following entry and replace the two placeholder values with the credentials supplied by Grade.
{ "mcpServers": { "grade": { "command": "npx", "args": ["-y", "@usegrade/mcp-server@latest"], "env": { "GRADE_APPLICATION_ID": "app_...", "GRADE_API_KEY": "sk_..." } } } } -
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.
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, creator directories, payment templates, content review, payout approvals, and campaign or standalone analytics.
Enable write tools
Write tools are not registered unless you explicitly enable them. Add this environment variable to the same env object:
{
"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.
Safer payout flow
- Trigger the payout with
requireConfirmation: trueand a uniqueidempotencyKey. - Review the returned payout preview, including the recipient, amount, currency, and platform fee.
- 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, transaction, and invoice 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.
401response: Verify the application ID and API key belong to the same active SDK application.403response: 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_BYTESonly when needed. - Write tool is missing: Set
GRADE_MCP_ENABLE_WRITEStotrue, then restart the client.
Platform workflow tools
The MCP catalog includes media freeze/unfreeze, restore, restart-from-date, tracking settings, manual analytics, review decisions, scoring, campaign completion/reopening, template application, payment adjustments, approval decisions, and collection bulk membership/freezing. These write tools still require GRADE_MCP_ENABLE_WRITES=true and their SDK scopes. Approval tools require the separately granted approvals scopes; approving can execute a payout. The catalog does not expose campaign refresh/wake/pause controls or logo checks.
