Agent (MCP) documentation

Connection

Most clients (Claude, Cursor, Lovable, VS Code) only need the URL — they run the OAuth flow for you:

{
  "mcpServers": {
    "pay-it-forward": {
      "url": "https://sharepayitforward.com/mcp"
    }
  }
}

Raw HTTP, if you already hold a token:

curl -X POST https://sharepayitforward.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Access levels

Public tools work for any authenticated agent account. Operator tools additionally require the account to hold the admin role; anything else returns an error result rather than partial data. No tool writes data — every tool is read-only and safe to retry.

Tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_grants",
    "arguments": { "status": "issued", "limit": 2 }
  }
}

{
  "content": [
    {
      "type": "text",
      "text": "Grants 1-2 of 14\nISSUED · $5.00 · Coffee for the night shift → Sacred Heart ER (Spokane, WA)\nISSUED · $5.00 · Art supplies → Ms. Rivera's class (Spokane, WA)"
    }
  ],
  "structuredContent": {
    "grants": [
      {
        "title": "Coffee for the night shift",
        "recipient": "Sacred Heart ER",
        "location": "Spokane, WA",
        "category": "gratitude",
        "amountCents": 500,
        "status": "issued",
        "issuedAt": "2026-08-14T00:00:00.000Z",
        "proofUrl": "https://sharepayitforward.com/grant-ledger"
      }
    ],
    "total": 14,
    "limit": 2,
    "offset": 0,
    "nextOffset": 2
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_ripple_report",
    "arguments": { "month": "2026-08" }
  }
}

{
  "content": [{ "type": "text", "text": "Ripple report for 2026-08\nMembers joined: 12\nGross received: $85.00 …" }],
  "structuredContent": {
    "month": "2026-08",
    "grossCents": 8500,
    "stripeFeeCents": 540,
    "platformFeeCents": 1200,
    "poolCents": 6760,
    "grantsIssuedCents": 2500,
    "grantsPlannedCents": 1500,
    "memberCount": 12
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_members",
    "arguments": { "status": "active", "limit": 1 }
  }
}

{
  "content": [{ "type": "text", "text": "Members 1-1 of 4\nx7viegaz · active · joined 2026-09-05 · referred by s4hhud93" }],
  "structuredContent": {
    "members": [
      {
        "rippleCode": "x7viegaz",
        "email": "member@example.com",
        "joinedAt": "2026-09-05T18:12:04.221Z",
        "membershipStatus": "active",
        "referredBy": "s4hhud93"
      }
    ],
    "total": 4,
    "limit": 1,
    "offset": 0,
    "nextOffset": 1
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_payments",
    "arguments": { "status": "succeeded", "from": "2026-08-01", "limit": 1 }
  }
}

{
  "content": [{ "type": "text", "text": "Payments 1-1 of 9\n2026-09-05 · succeeded · $5.00 gross → pool $3.55, platform $1.00, stripe $0.45" }],
  "structuredContent": {
    "payments": [
      {
        "date": "2026-09-05T18:12:04.221Z",
        "status": "succeeded",
        "email": "member@example.com",
        "grossCents": 500,
        "stripeFeeCents": 45,
        "platformFeeCents": 100,
        "poolCents": 355,
        "currency": "usd"
      }
    ],
    "total": 9,
    "limit": 1,
    "offset": 0,
    "nextOffset": 1
  }
}

Conventions

• All money is integer cents; currency is USD unless a row says otherwise.
• All timestamps are ISO 8601 in UTC.
• Paginate with limit and offset; keep calling while nextOffset is not null.
• Every result carries both a human-readable content[0].text summary and machine-readable structuredContent. Parse the latter.

Errors

Failures come back as a tool result with isError: true and a plain-text reason, not a transport error.

{
  "content": [{ "type": "text", "text": "Admin access required" }],
  "isError": true
}