Get started

Connect your agent

Paycurb is an MCP tool server. Your agent calls create_order on Paycurb instead of on PayPal. Paycurb checks the order against your policy, and only then talks to PayPal.

Sandbox endpoint

https://paycurb-proxy-rickygole32-8911s-projects.vercel.app/mcp

This is the proxy this site is set up with. It only talks to the PayPal sandbox. To run your own, start the proxy with pnpm proxy and use its address.

Quickstart

  1. Write the policy in plain English.

    Open the policy page in the demo. A model drafts the rules, you read them back, and nothing applies until you confirm.

    Open the policy
  2. Point your agent at the endpoint.

    Add Paycurb as an MCP server. The tool names match the PayPal agent toolkit: create_order, get_order and create_refund.

    See the config
  3. Watch decisions in the feed.

    Every call shows up live with its rule, its reason and its PayPal reference.

    Open the feed
  4. Approve held orders.

    Orders over your approval line wait for the owner. Approve, and the agent repeats the same call to pay.

    Open approvals

1. Add the MCP server

Any MCP client that speaks streamable HTTP works. The x-agent-id header names the agent in the log. Without it the agent is recorded as demo-agent.

MCP client config

{
  "mcpServers": {
    "paycurb": {
      "type": "http",
      "url": "https://paycurb-proxy-rickygole32-8911s-projects.vercel.app/mcp",
      "headers": {
        "x-agent-id": "office-agent"
      }
    }
  }
}

Or connect from code with the MCP TypeScript SDK

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "office-agent", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(new URL("https://paycurb-proxy-rickygole32-8911s-projects.vercel.app/mcp"), {
  requestInit: { headers: { "x-agent-id": "office-agent" } },
});
await client.connect(transport);

2. Call create_order

Costs are in dollars, as in PayPal. payee is the merchant's payee reference. Paycurb hashes the whole order, so the approval for it covers this exact order and nothing else.

Tool call

const result = await client.callTool({
  name: "create_order",
  arguments: {
    "currencyCode": "USD",
    "payee": "acme-office@merchants.example",
    "items": [
      {
        "sku": "LAMP-1",
        "name": "Desk lamp",
        "quantity": 1,
        "itemCost": 75,
        "itemTotal": 75
      }
    ]
  },
});
const answer = JSON.parse(result.content[0].text);

3. Handle the answer

Every result is one JSON text block with decision, rule_id and reason. The reason is plain English, so the agent can pass it to the person it works for.

Allowed

The order went to the PayPal sandbox and was captured. order.id is the PayPal order and capture_id is the capture.

Allowed response

{
  "decision": "allow",
  "rule_id": "R99",
  "reason": "Executed at PayPal: COMPLETED",
  "order": {
    "id": "ORDER_ID",
    "status": "COMPLETED",
    "capture_id": "CAPTURE_ID"
  }
}

Held

Nothing is paid yet. The owner approves it on the approvals page. Then the agent repeats the identical call, optionally with approval_id, and Paycurb pays it. Calling again before a decision returns the same hold. The approval is single use and expires.

Held response

{
  "decision": "escalate",
  "rule_id": "R14",
  "reason": "Needs approval: $75.00 is at or above the $50.00 auto-approve line",
  "approval_id": "APPROVAL_ID"
}

Blocked

Nothing reached PayPal. rule_id says which rule stopped it and reason says why. The block is written to the audit log like everything else.

Blocked response

{
  "decision": "block",
  "rule_id": "R04",
  "reason": "Blocked: luxury-watches.example is not an approved merchant"
}

ORDER_ID, CAPTURE_ID and APPROVAL_ID stand in for the ids your run returns. Rules and reasons come from the demo policy.