Documentation

Everything you need to monetize your MCP tools with SettleGrid.

Quick Start

Get your first monetized tool running in under 5 minutes.

1. Install the SDK

Terminal

npm install @settlegrid/mcp

2. Register as a developer

Create a developer account and connect your Stripe account to receive payouts.

3. Create a tool

In your dashboard, create a tool with a unique slug and pricing configuration.

4. Wrap your handler

server.ts

import { settlegrid } from '@settlegrid/mcp'

const sg = settlegrid.init({
  toolSlug: 'weather-api',
  pricing: {
    defaultCostCents: 1,
    methods: {
      'get-forecast': { costCents: 2 },
      'get-historical': { costCents: 5 },
    },
  },
})

// Wrap any function — credits checked and deducted automatically
const getForecast = sg.wrap(
  async (args: { city: string }) => {
    const data = await fetchWeatherData(args.city)
    return { forecast: data }
  },
  { method: 'get-forecast' }
)

// Use in your MCP server
server.tool('get-forecast', getForecast)

5. Share your tool

Your tool gets a public storefront at settlegrid.ai/tools/your-slug. Consumers purchase credits and receive API keys to use your tool.

SDK Reference

`settlegrid.init(options)`

Initialize the SDK for your tool.

interface InitOptions {
  toolSlug: string          // Your tool's unique slug
  apiUrl?: string           // API URL (default: https://settlegrid.ai)
  pricing: {
    defaultCostCents: number  // Default cost per call in cents
    methods?: Record<string, {
      costCents: number       // Method-specific cost
      displayName?: string    // Optional display name
    }>
  }
  debug?: boolean           // Enable debug logging
  cacheTtlMs?: number       // Key validation cache TTL (default: 5min)
  timeoutMs?: number        // API timeout (default: 5000ms)
}

`instance.wrap(handler, options?)`

Wraps a function with billing middleware. The wrapped function extracts the API key, validates credits, executes your handler, and meters the usage.

const wrappedFn = sg.wrap(
  async (args: MyArgs) => { /* your logic */ },
  { method: 'my-method' }  // Optional: defaults to 'default'
)

// Call the wrapped function with context
const result = await wrappedFn(args, {
  headers: { 'x-api-key': 'sg_live_...' },
  // or metadata: { 'settlegrid-api-key': '...' }
})

Error Handling

import {
  InvalidKeyError,         // 401 - Invalid API key
  InsufficientCreditsError, // 402 - Not enough credits
  ToolNotFoundError,        // 404 - Tool not found
  RateLimitedError,         // 429 - Rate limited
} from '@settlegrid/mcp'

try {
  const result = await wrappedFn(args, ctx)
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log(`Need ${err.requiredCents}¢, have ${err.availableCents}¢`)
  }
}

API Reference

The SettleGrid REST API is available at https://settlegrid.ai/api.

POST/api/auth/developer/registerRegister developer account

POST/api/auth/developer/loginDeveloper login

GET/api/auth/developer/meGet developer profile

POST/api/toolsCreate tool

GET/api/toolsList developer tools

PATCH/api/tools/:idUpdate tool

PATCH/api/tools/:id/statusToggle tool status

GET/api/tools/public/:slugGet tool storefront data

POST/api/sdk/validate-keyValidate API key (SDK internal)

POST/api/sdk/meterMeter invocation (SDK internal)

POST/api/consumer/keysCreate consumer API key

POST/api/billing/checkoutCreate checkout session

GET/api/payoutsList payout history

POST/api/payouts/triggerRequest manual payout

Pricing Model

SettleGrid uses a simple, transparent pricing model:

Developers: Free to sign up. Set your own prices. Keep 80% of revenue.
Consumers: Prepaid credits. Purchase $5, $20, $50, or custom amounts.
Platform fee: 20% of each transaction. No monthly fees, no minimums.
Payouts: Weekly or monthly via Stripe Connect. $25 minimum.

FAQ

How fast is the billing middleware?

The SDK uses an in-memory LRU cache for key validation (5-minute TTL) and fires metering requests asynchronously. Typical overhead is under 10ms.

What happens if the SettleGrid API is down?

The SDK caches key validations locally. If the metering API is unavailable, invocations are queued and retried. Your tool continues to work.

Do credits expire?

No. Credits purchased for a specific tool never expire and can be used at any time.

Can I set different prices for different methods?

Yes. The pricing config supports per-method pricing overrides. You can set a default cost and then override specific methods.

How do I handle refunds?

Contact support to process refunds. Refunded credits are returned to the consumer's balance.