Model Context Protocol · v2025-03-26

MCP Server

The same six tools that power the workspace are callable from any MCP client — Claude Desktop, Cursor, mcp-cli, or your own agent. Bearer-auth gated, JSON-RPC over HTTP, stdio fallback included.

Online

HTTP endpoint

POST /api/mcp · Bearer-auth · JSON-RPC 2.0

Stdio fallback

pnpm --filter @paybridge/mcp stdio for Claude Desktop

Six tools advertised

list_patterns, recommend_pattern, generate_code, explain, run_harness, check_guardrails

Why this matters

MCP — the Model Context Protocol — is the emerging standard for letting AI agents call structured tools instead of free-typing into a browser. Anthropic, OpenAI, and every major IDE are converging on 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.

Pitch

Any AI agent — Claude Desktop, Cursor, an autonomous build pipeline — can drive PayBridge end-to-end. Generate the code, run the harness, check guardrails, 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–G5 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"
}

Connect a client

Pick your client + transport. HTTP is the canonical surface — works from any terminal, no repo checkout needed. Stdio wraps HTTP via a local proxy 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-G5 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 6 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

All six tools are read-only or sandbox-only: generate_code writes only to generated_artefacts, run_harness only to integration_runs, guardrails to guardrail_results. No production funds are reachable.