Prerequisites
- Node.js 20 or newer
- A Grade SDK application ID and API key
Connect your client
1
Open the MCP configuration
Open the JSON configuration used by your MCP-compatible client.
2
Add the Grade server
Add the following entry and replace the two placeholder values with the credentials supplied by Grade.
3
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.
Enable write tools
Write tools are not registered unless you explicitly enable them. Add this environment variable to the sameenv object:
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.
Optional settings
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 requireGRADE_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.