PayRam MCP Server — Self-Hosted Crypto Payments for AI Agents
Self-hosted crypto and stablecoin payments: no account lock, no fund freeze, customer data never shared. Your AI agent can plan, install and operate it over MCP.
Hosted endpoint: https://mcp.payram.com/mcp · Website · Docs · Agentic · OpenClaw
An MCP (Model Context Protocol) server that lets any MCP-aware AI agent — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot, and others — deploy, integrate, and operate a self-hosted PayRam crypto-payment stack.
Start here: four tools lead the catalog:
| Tool | What it does |
|---|
payram_setup_plan | A personalised install plan, with every human hand-off marked |
payram_doctor | A public, credential-free check of a PayRam server by URL |
payram_troubleshoot | Describe a problem or paste an error: known causes, how to confirm, the fix, and the next tool |
payram_runbook | Admin tasks: Site URL, domain, SSL, firewall, upgrade, backup, chains, Smart Bridge, Shopify/WooCommerce |
payram_ops_playbook | Day-2 API recipes the agent runs itself with its own credentials |
Around them sit codebase assessment, starter-app scaffolds, multi-language snippets and inline docs.
The hosted server (mcp.payram.com) never holds merchant credentials. Day-2 operations run through payram_ops_playbook: the agent calls your PayRam API directly, and the credentials never leave its machine. The live data tools (payment search, payment links, node sync, worker restart) and assess_payram_project exist only when you run the MCP yourself in local mode.
For agents & crawlers: server card · skills index · llms.txt · sitemap. The server also answers Accept: text/markdown on / with an agent-readable summary.
What is PayRam? · PayRam 是什么?
PayRam is a self-hosted, multi-chain crypto payment gateway you own outright — with no signup and no KYC/KYB to run it. An AI agent (or a developer) can stand up a store and start accepting payments without registering an account with PayRam, a bank, or any payment processor. Deploy on your own VPS, generate API keys locally, go live.
What makes it different:
- Nobody can lock you out — there is no account to lock and no funds to freeze. Customer data is never shared, and nothing is reported or monitored. The reason is simple: PayRam runs on your server and funds land in your own wallet.
- Permissionless setup — no signup, no KYC, no KYB. Nobody approves you; nobody can switch you off. Ideal for agents spinning up stores autonomously, and for markets like China where registering with a Western processor isn't an option.
- Card-to-crypto checkout — shoppers without crypto can pay with a credit/debit card and you receive crypto, settled straight into your self-custodied wallet. It is a built-in channel you switch on from the Payments page; the card provider runs its own checks on the shopper.
- Multi-chain — accept BTC, ETH, USDT, USDC, and TRX natively across Bitcoin, Ethereum, Base, Polygon, and Tron, with automatic deposit detection, on-chain confirmation, sweeps to cold storage, and signed webhooks. Smart Bridge rails also take payments on Solana, Bitcoin, Tron (USDT) and BNB Chain and settle them as USDC on Base.
- No deposit keys on the server — smart contracts sweep deposits to your cold wallet, so a compromised server cannot redirect them. The server's hot wallet pays gas and signs payouts, so keep its balance small.
PayRam 是一个你完全自托管、自主拥有的多链加密货币支付网关——运行它无需注册、无需 KYC/KYB。 AI 智能体(或开发者)无需在 PayRam、银行或任何支付处理商处注册账户,即可搭建店铺并开始收款。在自己的 VPS 上部署,本地生成 API 密钥,即刻上线。
核心差异:
- 没有人能把你锁在门外 — 没有可被封禁的账户,也没有可被冻结的资金;客户数据从不外泄,也没有任何上报或监控。原因很简单:PayRam 运行在你自己的服务器上,资金直接进入你自己的钱包。
- 免注册、免许可 — 无需注册、无需 KYC、无需 KYB。没有人审批你,也没有人能关停你。非常适合自主搭建店铺的智能体,以及像中国这样难以在西方支付处理商处注册的市场。
- 银行卡转加密货币结算 — 没有加密货币的买家也能用信用卡/借记卡付款,你直接收到加密货币并结算到自托管的钱包。这是内置的支付渠道,在「Payments(支付)」页面开启;银行卡服务商会对买家进行其自身的审核。
- 多链支持 — 原生支持在 Bitcoin、Ethereum、Base、Polygon、Tron 上接受 BTC、ETH、USDT、USDC、TRX,自动检测充值、链上确认、归集冷钱包并发送带签名的 Webhook。Smart Bridge 通道还可接收 Solana、Bitcoin、Tron(USDT)和 BNB Chain 上的付款,并以 Base 上的 USDC 结算。
- 服务器上没有充值私钥 — 智能合约把充值资金归集到你的冷钱包,即便服务器被攻破也无法改变资金去向。服务器上的热钱包负责支付 Gas 并签署出款,请只保留少量余额。
How AI agents use PayRam · AI 智能体如何使用 PayRam
PayRam is agent-first infrastructure. Because integration is over MCP, it works with any MCP-aware runtime — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain, and more. A typical agent flow:
- Connect — add
https://mcp.payram.com/mcp to the agent's MCP config (no API key needed just to connect).
- Plan — call
payram_setup_plan. It returns the ordered steps, who runs each one, and where the agent must stop for the human (cold wallet, mainnet gas, root-only settings).
- Install — on the VPS, in an interactive terminal once, run
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (or --mainnet; the installer default is mainnet, so always pass the flag). Never pipe it into bash.
- Hand off — the human claims the root account right away and saves Settings → Site URL from the public domain; until then, payment links point at
http://localhost.
- Check —
payram_doctor with the public URL (no credentials needed).
- Accept payments — drop in framework-specific integration code from the snippet tools. Webhooks are signed (
X-Payram-Signature, HMAC-SHA256 of the raw body with the project API key).
- Operate —
payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) gives the agent the exact API calls to run with its own credentials. payram_runbook covers admin changes.
{
"mcpServers": {
"payram": { "url": "https://mcp.payram.com/mcp" }
}
}
For the OpenClaw-specific walkthrough (registration, testnet on Base Sepolia, chat-commerce patterns for WhatsApp/Telegram/Discord) see the payram-openclaw-integration skill and payram.com/openclaw.
PayRam 是智能体优先(agent-first)的基础设施。由于集成基于 MCP 协议,它可与任何兼容 MCP 的运行时配合使用——OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能体使用流程:连接 MCP 端点 → 调用 payram_setup_plan 规划安装 → 在交互式终端中用 bash <(curl …) --testnet 部署网关 → 由人工立即创建 root 账户并在公网域名下保存 Site URL → 用 payram_doctor 检查 → 用集成代码收款(Webhook 带 X-Payram-Signature 签名)→ 通过 payram_ops_playbook 用智能体自己的凭证运维。托管的 MCP 服务器从不保存商户凭证。
If GitHub is hard to reach from your network, you can mirror this repository to another Git host (git clone --mirror https://github.com/PayRam/payram-mcp.git).
如果你的网络难以访问 GitHub,可以把本仓库镜像到其他 Git 托管平台(git clone --mirror https://github.com/PayRam/payram-mcp.git)。
Table of Contents
Agent Skills
Agent front door: https://mcp.payram.com/SKILL.md — a single root skill that describes PayRam and routes agents to the four start-here tools. Also served: /llms.txt.
This repository includes 19 Agent Skills for AI coding assistants. Install them via skills.sh:
Install individually
npx skills add payram/payram-mcp/payram-setup
npx skills add payram/payram-mcp/payram-agent-onboarding
npx skills add payram/payram-mcp/payram-auth
npx skills add payram/payram-mcp/payram-analytics
npx skills add payram/payram-mcp/payram-crypto-payments
npx skills add payram/payram-mcp/payram-payment-integration
npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
npx skills add payram/payram-mcp/payram-checkout-integration
npx skills add payram/payram-mcp/payram-widget-integration
npx skills add payram/payram-mcp/payram-webhook-integration
npx skills add payram/payram-mcp/payram-stablecoin-payments
npx skills add payram/payram-mcp/payram-bitcoin-payments
npx skills add payram/payram-mcp/payram-payouts
npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
npx skills add payram/payram-mcp/payram-openclaw-integration
npx skills add payram/payram-mcp/compare-crypto-payments
npx skills add payram/payram-mcp/payram-agent-journey
npx skills add payram/payram-mcp/payram-topup-wallet-integration
npx skills add payram/payram-mcp/payram-testnet-testing
| Skill | Purpose |
|---|
payram-setup | Install plan and server setup: requirements, installer, Site URL, wallets, first payment link |
payram-agent-onboarding | Headless install by an agent: agent CLI commands, env vars, human hand-offs |
payram-auth | JWT auth flow — signin, token refresh, logout, external-platform details |
payram-analytics | Payment search, volume, balances and sweep history via direct REST APIs (JWT) |
payram-crypto-payments | Architecture overview, why PayRam, MCP tools |
payram-payment-integration | Quick-start payment integration guide |
payram-self-hosted-payment-gateway | Deploy and own your payment infrastructure |
payram-checkout-integration | Checkout flow with SDK + HTTP for 6 frameworks |
payram-widget-integration | Safe "Add Credit" button (backend endpoint, never a public API key) + signed-webhook handlers |
payram-webhook-integration | Signed-webhook (HMAC) handlers for Express, Next.js, FastAPI, Gin, Laravel, Spring Boot |
payram-stablecoin-payments | USDT/USDC acceptance across EVM chains and Tron |
payram-bitcoin-payments | BTC with HD wallet derivation and mobile signing |
payram-payouts | Send crypto payouts and manage referral programs |
payram-no-kyc-crypto-payments | No-KYC, no-signup, permissionless payment acceptance |
payram-openclaw-integration | Integrate PayRam into OpenClaw / agent runtimes — MCP register, testnet, chat commerce |
compare-crypto-payments | Compare gateways: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402 |
payram-agent-journey | Start-here map: install (merchant or operator) → wallets → gas/sweep → integrate → test |
payram-topup-wallet-integration | Existing apps: credit crypto to a user balance, debit invoices from it — ledger + flows |
payram-testnet-testing | Pay your own payment link on testnet end-to-end before mainnet |
Project Goals
- Accelerate onboarding with a personalised setup plan, runbooks, env templates and per-framework playbooks.
- Operate without holding credentials: the hosted server checks a PayRam by URL (
payram_doctor) and hands agents exact API recipes (payram_ops_playbook) to run with their own credentials.
- Retrofit existing repos via the project assessment tool (local mode), which scans package manifests and
.env files, then recommends the right integration snippets.
- Provide copy/paste snippets spanning Payments, Payouts, Referrals, Webhooks, and multi-language backends (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
- Keep docs local so Copilot can explain PayRam concepts, flows, and referral dashboards without leaving the editor.
- Validate connectivity with read-only probes that never create payments (
payram_doctor, test_payram_connection).
Quick Start
Most agents only need the hosted endpoint, https://mcp.payram.com/mcp (see Connect from your MCP client). To run the server yourself:
- Install dependencies
This repo uses Yarn 1. Node 25 and later no longer ship Corepack, so on Node 26 install Yarn first with
npm install -g yarn.
- Configure environment (only needed for the local-mode data tools)
- Copy
.env.example to .env.
- Set
PAYRAM_BASE_URL to your PayRam URL, the same origin as the dashboard (e.g. https://pay.example.com).
- Set
PAYRAM_API_KEY, plus the JWT variables for the data tools. See Local mode.
- Run the server
- Add the MCP server to your client: see Connect from your MCP client. The local-mode URL is
http://localhost:3333/mcp.
- Health check
curl http://localhost:3333/healthz
Tip: When you tell Copilot "test payram" it will automatically run the readiness checklist, ensure .env exists, and only then call test_payram_connection with your real credentials. The behavior is defined by the Copilot automation prompt—no manual prompting required.
Connect from your MCP client
Endpoint: https://mcp.payram.com/mcp (Streamable HTTP, JSON-RPC over POST). There is no SSE endpoint, and /mcp/sse returns 410. No auth headers: the hosted server never holds merchant credentials, so yours stay on your machine and never go into chat.
| Client | Where | Settings |
|---|
| VS Code (Copilot Chat) | Settings → Copilot: Model Context Protocol → Add HTTP server | Name payram, URL above, headers empty |
| Cursor | Settings → MCP Servers → Add → HTTP | Name payram, URL above |
| Claude Desktop / Code | Settings → MCP Servers → Add HTTP server | Name payram, URL above |
| Any MCP client | Register an HTTP endpoint | URL above, no headers |
Verify: the tool list should start with payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook and payram_ops_playbook, followed by scaffold_payram_app and the generate_* snippet tools. Then try: "plan a PayRam install on pay.example.com", "check https://pay.example.com", "generate a FastAPI create-payment route", "give me a Next.js webhook handler".
Prompts: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops.
Resources: payram://docs/setup-guide, payram://docs/api-reference, and the templates payram://ops/playbook/{task} and payram://runbooks/{task}.
Copilot automation prompt
Paste this once into a fresh workspace to make "test payram" run the full readiness flow automatically:
You have access to the `payram` MCP server in this workspace.
Whenever I ask you to "test my Payram connection" (or I type "test payram"), follow this order:
1. Call `prepare_payram_test` (no inputs) and share the checklist verbatim.
2. Look for a `.env` in the workspace root; create one if missing.
3. Ensure `.env` defines `PAYRAM_BASE_URL` and `PAYRAM_API_KEY`. If either is
missing, call `generate_env_template` and append it (with TODOs) to `.env`.
Do NOT call `test_payram_connection` until real values are provided.
4. Once real values exist, call `test_payram_connection` with baseUrl/apiKey
from `.env`, show the structured result, and explain whether the
connection is healthy. If anything fails, run `payram_doctor` and follow
its ranked fixes.
Local mode
Run the MCP next to your own PayRam to get the live data tools:
list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients
create_payment_link, check_payment_readiness, check_node_sync, restart_payram_worker
assess_payram_project
PAYRAM_MCP_MODE=local yarn dev
- Mode:
PAYRAM_MCP_MODE=local selects local mode. It is also the default whenever the server is not running on Vercel. PAYRAM_MCP_MODE=hosted never reads credentials.
- Binding: local mode binds to
127.0.0.1 by default (port PORT, default 3333).
- Non-loopback binds: set
HOST (e.g. HOST=0.0.0.0), then:
- Set
MCP_ALLOWED_HOSTS (comma-separated hostnames accepted in the Host header).
- Set
MCP_SERVER_TOKEN; clients then send Authorization: Bearer <token>.
- If
PAYRAM_* credentials are set, the server refuses to start on a non-loopback HOST without MCP_SERVER_TOKEN. Prefer loopback plus an SSH tunnel.
- Credentials: the data tools read
PAYRAM_* from the environment (or .env):
PAYRAM_BASE_URL
PAYRAM_API_KEY (payment links)
PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, data tools)
PAYRAM_EXTERNAL_PLATFORM_ID (optional default project)
Example client config for a local server (local mode only):
{
"mcpServers": {
"payram-local": { "url": "http://localhost:3333/mcp" }
}
}
Credentials: which key for what
PayRam has two credentials — agents stall when they conflate them:
| Credential | Looks like | Used for | How an agent gets it (no dashboard needed) |
|---|
Merchant API key (PAYRAM_API_KEY, header API-Key) | per-project key | POST /api/v1/payment (payment links), merchant payouts, all merchant server-to-server calls, and it signs webhooks (X-Payram-Signature) | bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — reuses or mints the project key via POST /api/v1/external-platform/{id}/api-key and saves it to ~/.payraminfo/merchant-api-key.env |
JWT (Authorization: Bearer) | access+refresh token from signin | admin/setup APIs (projects, wallets, analytics) — payram_ops_playbook recipes and the local-mode data tools | bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (env PAYRAM_EMAIL/PAYRAM_PASSWORD); saved to ~/.payraminfo/headless-tokens.env |
The one-step setup flow (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) produces both automatically and prints where they live. The API is same-origin with the dashboard, on port 80/443 (https://<your-domain>/api/v1/..., or http://localhost on the server, never :8080). The API key can create payouts, so keep it server-side and never put it in browser code or chat. Use payram_ops_playbook task connect to set both up for direct API calls.
| Category | Tool | Purpose |
|---|
| Start here – Install | payram_setup_plan | Personalised, ordered install plan (prepare → install → claim root + Site URL → wallets + Smart Bridge → API key + first link → harden → integrate) with agent vs human steps and hard stops. |
| Start here – Diagnostics | payram_doctor, payram_troubleshoot | payram_doctor: public, credential-free staged check by URL (reachability → health → TLS → version → workers) with ranked likely causes + exact fixes. Optional API-key validity check that creates nothing. Run this FIRST when anything fails. payram_troubleshoot: match a symptom or pasted error to known causes and fixes. |
| Start here – Admin | payram_runbook | Step-by-step admin tasks with human gates: set_site_url, change_domain, ssl_setup, ssl_renewal_fix, firewall_ports, upgrade, backup, restore, add_chain, smart_bridge, mainnet_cutover, operator_setup, rotate_api_key, reset_test_install, shopify_connector, woocommerce_plugin, secure_analytics_mcp. |
| Start here – Operations | payram_ops_playbook | Direct-API recipes the agent runs itself: connect, health, version_check, workers, restart_worker, node_sync, site_url, payment_options, unswept_funds, payments_today, payment_lookup, stuck_payment, create_payment_link, payouts, webhooks, logs, daily_check. |
| Connectivity | test_payram_connection | Read-only reachability/health check plus optional API-key validation. Never creates payments. |
| Setup | generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup | Ship env boilerplate, merchant checklists, recommended project layouts, and the headless agent onboarding guide. |
| Context / Docs | explain_payram_basics, explain_payram_concepts, explain_payment_flow, explain_payram_security, get_payram_links, prepare_payram_test, get_payram_doc_by_id, list_payram_docs, etc. | Provide inline Markdown knowledge sourced from docs/ so Copilot can answer conceptual questions. Some tools append “say test payram” reminders automatically. |
| Integration – Payments | generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet | Emit SDK, raw HTTP, or Express/Next.js route code for create + status flows. |
| Integration – Payouts | generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet | Direct (no-OTP) payout, the 3-step saved-recipient flow (create recipient → validate OTP → pay out), and status polling. |
| Integration – Referrals | generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet | Cover referral auth, linking, validation, status, and express/next routes. |
| Integration – Webhooks | generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event | Produce handlers for Express/Next/FastAPI/Gin/Laravel/Spring Boot, fan-out routers, and cURL/Python/Go/PHP/Java webhook testers. |
| Integration – Multi-language Payments | snippet_* family (snippet_express_payment_route, snippet_nextjs_payment_route, snippet_fastapi_payment_route, snippet_laravel_payment_route, snippet_go_payment_handler, snippet_spring_payment_controller) | Prebuilt route handlers for Express, Next.js App Router, FastAPI, Gin, Laravel, and Spring Boot. |
| Integration – Top-Up Wallet | generate_topup_integration_snippet | For EXISTING apps: ledger schema + cumulative-credit webhook + atomic invoice settle, so over/under/late/duplicate crypto payments become balance states instead of payment exceptions. Pairs with the payram-topup-wallet-integration skill. |
| Integration – Project Assessment (local mode) | assess_payram_project | Scans package.json, requirements.txt, composer.json, go.mod, pom.xml, .env, etc. Reports detected frameworks, env status, PayRam dependencies, and prioritized next steps with tool suggestions. |
| Scaffolding | scaffold_payram_app | Generates full starter apps (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) with payments, payouts, webhooks, and a browser console. Put the payout endpoints behind your own admin auth before deploying. |
| Live Data (read-only, local mode) | list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients | Query live PayRam data. list_currencies is public (no key); the rest use the JWT tokens in .env. list_recipients pairs with the payout recipient flow. |
| Live Operations (local mode) | create_payment_link (write), check_payment_readiness, check_node_sync, restart_payram_worker (write) | create_payment_link creates a real checkout link via API-Key. check_payment_readiness reports per-chain gaps (missing wallet / currency / listener) to accept payments. check_node_sync reports listener-worker + RPC node health and block staleness. On the hosted server, use the matching payram_ops_playbook tasks. |
Tool registrations live in src/tools/index.ts; individual implementations sit in src/tools/** with language-specific templates under templates/ folders.
Guided Workflows
0. Install PayRam
- Ask: "Set up PayRam on pay.example.com" (or use the
setup-payram / setup-payram-agent prompts).
- The assistant calls
payram_setup_plan and walks the phases, stopping at every human step (root account, Site URL, cold wallet, mainnet gas).
- It finishes with
payram_doctor, backups (payram_runbook backup) and the daily check (payram_ops_playbook daily_check).
1. Assess and Retrofit an Existing Project
- Ask Copilot: "Can you integrate PayRam into this project?"
- The assistant runs
assess_payram_project (local mode), reviewing dependency manifests and .env.
- Follow the recommended steps (install
payram, request Express/FastAPI/Spring route snippets, add webhooks, etc.).
- Use
test_payram_connection once credentials are real to ensure the backend can reach your self-hosted server.
2. Scaffold a Fresh Sample
- "Create a PayRam Express demo" →
scaffold_payram_app builds an Express project with payments, payouts, webhooks, and a UI console.
- Drop the generated files into an empty repo or compare against your existing directory for reference wiring.
3. Run the "Test PayRam" Readiness Flow
- Say "test payram". The assistant automatically:
- Calls
prepare_payram_test to share the readiness checklist.
- Ensures
.env exists (creating it if missing) using generate_env_template.
- Waits for real credentials before invoking
test_payram_connection.
- Review the structured JSON result to confirm the PayRam API is reachable.
4. Wire Payments, Payouts, Referrals, and Webhooks
- Payments:
generate_payment_sdk_snippet (JS SDK) or generate_payment_http_snippet (Python/Go/PHP/Java).
- Multi-language routes:
snippet_nextjs_payment_route, snippet_fastapi_payment_route, etc.
- Payouts:
generate_payout_sdk_snippet for create + generate_payout_status_snippet for polling.
- Referrals:
generate_referral_route_snippet, generate_referral_validation_snippet.
- Webhooks:
generate_webhook_handler plus generate_webhook_event_router for fan-out + generate_mock_webhook_event to test each status.
Development
| Command | Description |
|---|
yarn dev | Run the MCP server with hot reload via tsx. |
yarn build | Compile TypeScript to dist/. |
yarn lint / yarn format | ESLint + Prettier across the repo. |
yarn test | Executes the Vitest suite (tests/). |
make precommit-test | Runs format → lint → test → build sequentially. |
Project is TypeScript-first (ESM). Prettier config lives in .prettierrc.json; ESLint is configured via eslint.config.mjs. Smooth contributions follow the commit helper in Makefile → make commit.
Troubleshooting
Start with payram_doctor — one read-only call that walks reachability → health → TLS → version → workers and returns ranked causes with exact fixes. For deeper checks, follow payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).
- Copilot doesn’t call the right tool: Check the Copilot automation prompt is installed and your MCP client loaded the server. Re-run "test payram" or "assess my project" to trigger the expected automation.
test_payram_connection fails with 401: Confirm the key is an active project API key (sent as the API-Key header, not Authorization).
- A data tool says credentials are unavailable: the hosted server never holds merchant credentials. Use the matching
payram_ops_playbook task, or run the MCP in local mode.
- Payment links show
http://localhost: the human must save Settings → Site URL from the public domain (payram_runbook task set_site_url).
- Docs tool says a file is missing: Verify your local
docs/payram-docs-live/ tree contains the requested markdown (get_payram_doc_by_id rejects paths with ..).
- Server won’t start: Ensure Node 22.12+ and run
yarn install. In local mode with a non-loopback HOST and PAYRAM_* credentials set, the server refuses to start until MCP_SERVER_TOKEN is set (see Local mode).
For anything else, inspect the structured logs emitted from src/utils/logger.ts (set LOG_LEVEL=debug) and open an issue/PR with reproduction details.