Skip to main content
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
Treat your API key like a password. Store it in the MCP client’s environment configuration, not in chat messages or tool arguments.

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.
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:
After restarting the client, it can create or change payouts, KYC invites, campaigns, contracts, media, bonus templates, and analytics collections.
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.

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

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

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.