Model Context Protocol

MCP Server

The workspace tools and the Recovery Agent tools, callable from any MCP client.

Online

HTTP endpoint

POST /api/mcp · OAuth 2.1 or bearer token · JSON-RPC 2.0

One command to connect

claude mcp add --transport http paybridge … · no repo checkout, no config file

16 tools advertised

6 integration tools (generate, test, check) and 10 Recovery Agent tools (recovery_*)

Why this matters

MCP, the Model Context Protocol, is the open standard that lets AI agents call structured tools instead of typing into a browser. Anthropic, OpenAI and the major IDEs support it.

PayBridge ships an MCP server out of the box. The same generate_code / run_harness / check_guardrails tools that Pulse fires inside the workspace become callable from any external MCP client.

In short

Any AI agent, from Claude Desktop to Cursor to a build pipeline, can drive PayBridge end to end: generate the code, run the test, check security, then ship.

Read the MCP spec

Tool catalogue

Every tool below is callable via tools/call. Inputs are validated with zod before execution; outputs are returned as both a human-readable text block and a machine-readable structuredContent field. Each tool ships pre-built example payloads — pick one, copy the JSON, paste it into your MCP client's tool form.

list_patterns

Discover supported (provider × pattern × language) combinations.

{ }

Empty input. Returns the three patterns with their current availability (live vs code-ready).

{}
recommend_pattern

Given a provider + optional use-case, suggest the best pattern + two alternatives.

{ providerId, useCase? }

Should return tokenized-card-vault with the non-profit-aware rationale.

{
  "providerId": "braintree",
  "useCase": "monthly recurring donor giving for a non-profit sustainer program"
}
generate_code

Produce a complete Next.js TypeScript scaffold for a (provider, pattern). Snapshots an artefact for guardrail replay.

{ providerId, pattern, appName?, currency?, amount? }

Returns 4 files: server route, client Hosted Fields page, webhook receiver, .env.example.

{
  "providerId": "braintree",
  "pattern": "hosted-checkout",
  "currency": "USD",
  "amount": 1234
}
explain

Plain-English explainer for a PayBridge concept (idempotency, webhook, OAuth, …).

{ topic }

Cover G4 + provider-native primitives.

{
  "topic": "idempotency"
}
run_harness

Drive a real sandbox charge end-to-end: auth → checkout → tokenize → charge → webhook → idempotency replay.

{ providerId, pattern, amount?, currency?, testCardAlias?, artefactId? }

Full 6-step harness against Braintree sandbox.

{
  "providerId": "braintree",
  "pattern": "hosted-checkout",
  "amount": 1234,
  "currency": "USD"
}
check_guardrails

Run G1–G6 deterministic gates against the artefact attached to a run. Returns per-gate verdict + evidence.

{ runId, enabledGates? }

Paste a run id from /runs. Returns per-gate verdict + file:line evidence.

{
  "runId": "REPLACE_WITH_RUN_ID"
}

Recovery Agent tools

The Recurring-Gift Recovery Agent’s tools, under a recovery_ prefix. Over MCP the assistant you are using acts as the agent: it investigates each failed gift with these tools and proposes a plan. Every tool is read-only and runs on synthetic data; plans wait for staff approval in the PayBridge console, and every donor message carries an AI disclosure line.

recovery_list_failed_gifts

List failed recurring gifts

recovery_get_failed_gift

Get a failed gift

recovery_get_donor_payment_history

Donor payment history

recovery_lookup_decline_code

Look up a decline code

recovery_check_card_updater

Check the card updater

recovery_check_retry_budget

Check the retry budget

recovery_forecast_retry_success

Forecast retry success

recovery_draft_donor_message

Draft a donor message

recovery_submit_decision

Propose a recovery plan

recovery_backtest_summary

Backtest summary

Try it in Claude Desktop: pick the triage-failed-recurring-gifts prompt from the prompts menu, or ask “Triage today’s failed recurring gifts with the PayBridge recovery tools.”

Connect with OAuth

For clients that sign in rather than take a pasted token. PayBridge is an OAuth 2.1 authorization server for its own MCP endpoint: discovery, dynamic client registration, authorization code with PKCE (S256), and rotating refresh tokens. Access tokens last an hour; refresh tokens 30 days.

Claude Desktop and claude.ai

  1. 1Settings → Connectors → Add custom connector.
  2. 2URL: https://paybridge.vyaptix.ai/api/mcp. Leave the OAuth client fields empty; Claude registers itself.
  3. 3Click Connect. A PayBridge approval page opens.
  4. 4Enter the MCP access code and approve. The PayBridge tools appear in Claude.

Blackbaud AI Chat (partner MCP registration)

  1. 1Register a client in the card below. It gives you a client ID and a client secret.
  2. 2MCP server URL: https://paybridge.vyaptix.ai/api/mcp
  3. 3Paste the client ID and client secret into the registration form.
  4. 4Callback URL (already the card’s default): https://app.blackbaud.com/oauth/callback/mcp
  5. 5The first time someone connects, they approve on the PayBridge page with the access code. Sign in with Blackbaud will replace the access code later.

Register a client

For platforms that ask for a client ID and secret up front, such as Blackbaud AI Chat. Claude registers itself, so it does not need this. You need the MCP access code.

Connect a client

Pick your client + transport. HTTP is the canonical surface — works from any terminal, no repo checkout needed. Stdio wraps the same endpoint in @manizvlabs/paybridge-mcp, published to npm, for clients that only speak stdio. Replace <your token> in every snippet below with your MCP_DEMO_TOKEN (the same value Vercel has set for this deployment).

Client
Transport

Claude Code · HTTP transport (recommended)

Run from any terminal — no repo checkout needed

claude mcp add --transport http paybridge \
  https://paybridge.vyaptix.ai/api/mcp \
  --header "Authorization: Bearer <your token>"

# Verify the server registered + is reachable:
claude mcp list   # paybridge → Status: ✓ Connected

HTTP prerequisites: none. The client connects directly to https://paybridge.vyaptix.ai/api/mcp. No repo, no Node, no install. This is the simplest path and the one we recommend.

Once connected — what to say

Speak naturally. The model picks the right tool + fills the JSON. Use these prompts as starters; pair with the Examples dropdowns on each tool card above for tighter payload control.

  • List supported patterns

    Say "Show me what patterns PayBridge supports."

  • Pick a pattern for monthly giving

    Say "Ask PayBridge what pattern to use for monthly donor giving on Braintree."

  • Generate vault code

    Say "Use PayBridge to generate Braintree tokenized-card-vault code for a non-profit monthly sustainer program. USD 25."

  • Fire a real harness

    Say "Run the PayBridge harness against PayPal hosted-checkout with USD 12.34."

  • Check guardrails

    Say "Run PayBridge guardrails G1-G6 against run <paste-run-id>."

  • Explain a concept

    Say "Explain the Blackbaud dual-credential model using the PayBridge explain tool."

Sanity-check before wiring a client

Prove the endpoint + token work from your terminal first. If these 4 curls succeed, every MCP client will too. Replace <your token> with your token; or export PAYBRIDGE_MCP_TOKEN=… and substitute $PAYBRIDGE_MCP_TOKEN.

1. tools/list — verify auth + endpoint

Expect a JSON envelope with the 16 tools.

curl -sS https://paybridge.vyaptix.ai/api/mcp \
  -H "Authorization: Bearer <your token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

2. tools/call → list_patterns

Expect 3 patterns with live/code-ready availability.

curl -sS https://paybridge.vyaptix.ai/api/mcp \
  -H "Authorization: Bearer <your token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_patterns","arguments":{}}}'

3. tools/call → recommend_pattern (donor giving)

Expect "tokenized-card-vault" with non-profit rationale.

curl -sS https://paybridge.vyaptix.ai/api/mcp \
  -H "Authorization: Bearer <your token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"recommend_pattern","arguments":{"providerId":"braintree","useCase":"monthly recurring donor giving for a non-profit sustainer program"}}}'

4. tools/call → run_harness (writes a real /runs row)

Open /runs after — new row appears with Source = MCP.

curl -sS https://paybridge.vyaptix.ai/api/mcp \
  -H "Authorization: Bearer <your token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"run_harness","arguments":{"providerId":"braintree","pattern":"hosted-checkout","amount":1234,"currency":"USD"}}}'

Token hygiene. The token in every snippet is the literal placeholder <your token>. Paste your real MCP_DEMO_TOKEN only into your local client config — never into shared screenshots, support tickets, or chat transcripts.

If it leaks: rotate via Vercel → Settings → Environment Variables → edit MCP_DEMO_TOKEN to a fresh value → redeploy the latest deployment. Every client config you handed out becomes invalid the moment the new deployment goes live.

Token rotation & safety

One bearer token

The server reads MCP_DEMO_TOKEN from environment. Closed by default if unset.

Rotate any time

Update the env var on Vercel (or in .env locally) and restart. Clients pick up the new token on next call.

Read-only by default

Every tool is read-only or sandbox-only: generate_code writes only to generated_artefacts, run_harness only to integration_runs, guardrails to guardrail_results, and the recovery_* tools only read synthetic data. No production funds are reachable.