Connect an agent
Four ways to put an agent behind Verdock: the gateway, the Python SDK, the npm SDK and the MCP server. Your code never uploads to us and provider keys are read only on your machine.
On this page
Four ways to put an agent behind Verdock. All four decide before the action, and every answer carries a signed receipt.
| Way | Use it when | What leaves your machine |
|---|---|---|
| Gateway | The agent already calls a provider API. Change only the base URL. | The request to the gateway, which the workspace decides and forwards in test mode. |
| Python SDK | You write the agent in Python. | A decision record: operation, amount, currency, a masked counterparty id and a key. Nothing in local only mode. |
| npm SDK | You write the agent in Node. | The same decision record. |
| MCP server | The agent is Claude Desktop, Claude Code, Cursor or another MCP app. | The same decision record. |
Gateway#
Each workspace has a gateway URL that proxies the PayPal sandbox API in test mode. Change only your base URL. Send a PayPal-Request-Id so a retry never pays twice. Your own PayPal credentials in the Authorization header are forwarded and never stored.
PAYPAL_BASE = "https://getverdock.com/v1/gateway/paypal"
Authorization: Bearer vk_test_YOUR_KEYPayouts (POST /v1/payments/payouts) and capture returns are decided, then forwarded. Reads pass through. Everything else is refused.
Python and npm#
from verdock import Verdock
vd = Verdock(api_key="vk_test_YOUR_KEY", base_url="https://getverdock.com")
d = vd.check("payout", 1500, "USD", "order-4417")
if d.executed:
... # make your provider callimport { Verdock } from "verdock";
const vd = new Verdock({ apiKey: "vk_test_YOUR_KEY", baseUrl: "https://getverdock.com" });
const d = await vd.check("payout", 1500, "USD", "order-4417");curl -X POST https://getverdock.com/v1/actions \
-H "Authorization: Bearer vk_test_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"operation":"payout","amount_minor":1500,"currency":"USD","counterparty_id":"order-4417","idempotency_key":"order-4417-payout-1"}'Local only mode, Verdock(local_policy="verdock.yaml"), decides on your machine and sends nothing. To decide and sign locally with the open source package, use the guard in the quickstart.
pip install ./sdk/python
npm install ./sdk/jsMCP server#
The server gives your agent three tools that go through your policy: verdock_check decides before any action runs, verdock_request_approval reads or waits for the approval of a held action, and verdock_receipt fetches the signed receipts of an action and verifies the chain.
claude mcp add verdock --env VERDOCK_API_KEY=vk_test_YOUR_KEY --env VERDOCK_BASE_URL=https://getverdock.com -- python -m verdock.mcp{"mcpServers": {"verdock": {"command": "python", "args": ["-m", "verdock.mcp"],
"env": {"VERDOCK_API_KEY": "vk_test_YOUR_KEY", "VERDOCK_BASE_URL": "https://getverdock.com"}}}}{"mcpServers": {"verdock": {"command": "python", "args": ["-m", "verdock.mcp"],
"env": {"VERDOCK_API_KEY": "vk_test_YOUR_KEY", "VERDOCK_BASE_URL": "https://getverdock.com"}}}}Claude Desktop reads claude_desktop_config.json. Cursor reads .cursor/mcp.json.
Next#
Set the limits the agent runs under in the policy file. Read the exact request and answer shapes in the HTTP API.