Documentation / SDK v1

MCP server

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

mcp server · json
    {
      "mcpServers": {
        "grade": {
          "command": "npx",
          "args": ["-y", "@usegrade/mcp-server@latest"],
          "env": {
            "GRADE_APPLICATION_ID": "app_...",
            "GRADE_API_KEY": "sk_..."
          }
        }
      }
    }
All 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

  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.

    {
      "mcpServers": {
        "grade": {
          "command": "npx",
          "args": ["-y", "@usegrade/mcp-server@latest"],
          "env": {
            "GRADE_APPLICATION_ID": "app_...",
            "GRADE_API_KEY": "sk_..."
          }
        }
      }
    }
  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:

{
  "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

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

Describe your program.

Grade turns it into a program it can track and pay.