feat: add Arc payment MCP endpoint

.agent/context/20260913T021012Z-clarify-personal-mcp-plan.md

@@ -0,0 +1,76 @@
+# Session Context: clarify-personal-mcp-plan
+
+## Date/time
+
+- UTC: 2026-09-13T02:10:12Z
+
+## User goal
+
+Split the PR #112 plan into clear, ordered subtasks and reduce ambiguity about
+the first deliverable.
+
+## Original prompt/request
+
+"Раздели md plan, сделай четче на подзадачи." Follow-up: keep the plan focused
+only on the direct `arc_payment` flow.
+
+## Assumptions
+
+- The first release exposes exactly one MCP tool, `arc_payment`.
+- The first release reuses the existing Privy server execution wallet and Arc
+  settlement worker.
+- Personal wallets and additional signers are a later milestone.
+
+## Plan
+
+1. Rewrite the plan around one minimal server-wallet MCP milestone.
+2. Give every task dependencies, concrete work, and an exit condition.
+3. Preserve personal-wallet architecture as a separately gated milestone.
+4. Validate Markdown, obtain Gate A, update PR #112, wait for CI, then obtain
+   Gate B.
+
+## Key decisions
+
+- `arc_payment` is a direct Arc USDC transfer.
+- Browser and MetaMask wallets do not participate in milestone 1 payment
+  execution.
+- The MCP handler reuses existing durable intent and settlement paths.
+- Aggregate exposure needs a rolling cap or one-intent demo quota; a
+  per-payment cap alone is insufficient.
+
+## Files/components touched
+
+- `docs/PERSONAL_MCP_PRIVY_AGENT_PAYMENTS_PLAN.md`
+- `.agent/context/20260913T021012Z-clarify-personal-mcp-plan.md`
+
+## Commands/checks
+
+- `markdownlint-cli2` for the plan and context: PASS, 0 errors.
+- `git diff --check`: PASS.
+- Prettier check for the plan and context: PASS.
+
+## External-doc findings
+
+- Privy supports additional signers with per-signer override policies; this is
+  retained for milestone 2 rather than milestone 1.
+- Privy policy evaluation defaults to deny when no rule matches.
+
+## Unresolved questions
+
+- Choose a Privy rolling cap or a one-intent quota before the MCP endpoint is
+  exposed beyond a controlled demo.
+
+## Git and PR state
+
+- Branch: `plan/personal-mcp-privy-agent-payments`
+- Base: current `origin/develop` merged before editing.
+- PR: #112, draft.
+
+## Gate A/B state
+
+- Gate A: pending for the rewritten candidate tree.
+- Gate B: pending after push and CI.
+
+## Handoff/next steps
+
+- Complete Gate A, commit, push, CI, and Gate B.

.agent/context/20260913T022938Z-mcp-arc-payment.md

@@ -0,0 +1,104 @@
+# Session Context: MCP Arc payment
+
+## Date/time
+
+- UTC: 2026-09-13T03:01:00Z
+
+## User goal
+
+Continue implementing the PR #112 `arc_payment` plan on `mcp-integration`,
+test only locally, and leave deployment and the real Arc payment untouched.
+
+## Original prompt/request
+
+The user supplied a GLM5-3 review confirming Gate A, commit, push, and the MCP
+backend behavior at `1f25bae`, then asked: "Continue implementing plan, this was
+the review of GLM5-3." The standing constraint is: "Пока тестим все локально без
+запуска на develope."
+
+## Assumptions
+
+- The GLM5-3 review is accepted as the checkpoint for commit `1f25bae`.
+- Local tests use mocks and must not submit a live Arc payment.
+- Circle x402 and personal-wallet MCP support remain outside this milestone.
+
+## Plan
+
+1. Complete the missing public `/docs/mcp` guide and local same-origin proxy.
+2. Verify both themes and responsive layouts without invoking `arc_payment`.
+3. Stop before a fresh Gate A, commit, push, deployment, or live settlement.
+
+## Key decisions
+
+- Keep the page static and copy-ready, with no payment button or credential
+  persistence.
+- Reuse the existing brand tokens and theme machinery; add no dependency.
+- Keep the real Arc call pending because it is incompatible with local-only
+  testing.
+
+## Files/components touched
+
+- `apps/web/src/components/McpDocsPage.tsx`: public setup and replay walkthrough.
+- `apps/web/src/App.tsx`: `/docs/mcp` route and landing-page link.
+- `apps/web/src/styles.css`: responsive token-based documentation styles.
+- `apps/web/vite.config.ts`: local `/mcp` proxy to the API.
+- `apps/web/test/app-composition.test.tsx`, `apps/web/browser/p5.spec.ts`: route,
+  safety, contrast, responsive, and screenshot coverage.
+- `docs/MCP_ARC_PAYMENT.md`, `docs/PERSONAL_MCP_PRIVY_AGENT_PAYMENTS_PLAN.md`:
+  public route and implementation status.
+
+## Commands/checks
+
+- GLM5-3 reported API 81/81, Web 108/108, TypeScript, lint, diff check, and Gate
+  A PASS for `1f25bae`; PostgreSQL integration was not run locally because no
+  Docker runtime was available.
+- `pnpm --filter @oneshot/web test -- app-composition.test.tsx styles.test.ts` -
+  PASS, 25 tests.
+- `pnpm --filter @oneshot/web test` - PASS, 109 tests.
+- `pnpm --filter @oneshot/web typecheck` - PASS.
+- `pnpm --filter @oneshot/web lint` - PASS.
+- `pnpm --filter @oneshot/web test:browser` - PASS, 8 Chromium checks; the MCP
+  page passed axe color contrast and viewport overflow checks in light/dark at
+  390px and 1440px.
+- `pnpm test` - PASS, 83 files / 1091 tests.
+- `pnpm lint` and `pnpm format:check` - PASS.
+- `pnpm check:generated` - PASS; generated contracts are current.
+- `pnpm validate:fixtures` - PASS; 9 contract and 7 UI fixtures.
+- The host uses Node 22.23.2 while the repository pins Node 24.19.0; pnpm emits
+  the existing engine warning.
+
+## External-doc findings
+
+- No new external research was needed; the implementation follows the MCP SDK
+  and Streamable HTTP findings recorded with commit `1f25bae`.
+
+## Unresolved questions
+
+- The PostgreSQL MCP concurrency test still needs CI or a machine with Docker.
+- Deployment still needs the MCP bearer, request key, payer address, workspace,
+  and cap configuration in Cloud Run.
+- The real Arc Testnet call, identical replay, and proof capture remain pending.
+
+## Git and PR state
+
+- Branch: `mcp-integration`
+- Merged current `origin/develop` at
+  `94f2438fd2032a0cfa28699b0515c8ce6ed5300f` without restoring the removed
+  Circle paid API or seller.
+- MCP implementation commits: `1f25bae` and `f8baee7`; merge candidate is ready
+  for push and a draft implementation PR.
+- Post-merge local validation: `pnpm test` PASS, 78 files / 1043 tests;
+  `pnpm lint`, `pnpm format:check`, `pnpm check:generated`, and
+  `pnpm validate:fixtures` PASS; browser tests PASS, 8/8.
+
+## Review gates
+
+- Gate A: skipped for the merged implementation by explicit user instruction.
+- Gate B: skipped by explicit user instruction.
+
+## Handoff/next steps
+
+1. Commit and push the merge, open a draft PR, and wait for CI.
+2. Deploy the API and Worker with MCP configuration.
+3. Run one real Arc payment, replay the same request, and capture proof that no
+   replacement settlement was created.

.agent/context/20260913T033720Z-downloadable-arc-payment-skill.md

@@ -0,0 +1,102 @@
+# Session Context: Downloadable arc_payment agent skill
+
+## Date/time
+
+- UTC: 2026-09-13T03:37:20Z
+
+## User goal
+
+Ship a downloadable agent skill for the OneShot `arc_payment` MCP tool so
+users can install it, use the tool through their own MCP clients, and hand it
+to delegated/outsourced agents. Format: the repository standard
+`.agents/skills/<name>/SKILL.md`.
+
+## Original prompt/request
+
+Continuation of the PR #120 integration session. The user said: "мы должны
+сделать скилл для юзеров, которые они скачают, юзанут и смогут использовать и
+так же смогут отдавать на оутсорс" and later confirmed the assistant plan:
+"Теперь делаю скилл: скачаемый, для юзания и делегирования агентам — в
+стандартном формате репо .agents/skills/."
+
+## Assumptions
+
+- The skill rides the user-named integration branch `mcp-integration` (PR
+  #120), like the rest of the MCP milestone work.
+- Skill consumers are external agents (any tool with skills support); the
+  bearer token never travels inside the skill or prompts.
+- A `/docs/mcp` download link is a possible follow-up, not part of this change.
+
+## Plan
+
+1. Verify the drafted `.agents/skills/oneshot-arc-payment/SKILL.md` against
+   `apps/api/src/mcp.ts` and `docs/MCP_ARC_PAYMENT.md`.
+2. Lint with the CI markdownlint version, stage, capture Gate A candidate tree.
+3. Gate A, commit, push to `origin/mcp-integration`, wait for CI, Gate B,
+   record evidence in PR #120.
+
+## Key decisions
+
+- Skill-only change (docs file + this context record): no web/code surface, so
+  no test or browser-screenshot churn; smallest coherent change per policy.
+- Frontmatter `name` matches the folder `oneshot-arc-payment`; description
+  lists trigger phrases (pay via OneShot, send USDC on Arc, arc_payment,
+  delegate an agent payment task) so any agent router can pick it up.
+- Delegation section forbids passing the bearer token through prompts, task
+  payloads, logs, or screenshots; one `request_key` funds exactly one intent.
+- References point to the repo walkthrough, the human `/docs/mcp` page, and
+  the GitHub install path for the skill.
+
+## Files/components touched
+
+- `.agents/skills/oneshot-arc-payment/SKILL.md`: new downloadable skill
+  (prerequisites, `arc_payment` contract, execution flow, replay/conflict
+  handling, delegation rules, install references).
+- `.agent/context/20260913T033720Z-downloadable-arc-payment-skill.md`: this
+  record.
+
+## Commands/checks
+
+- Manual cross-check of SKILL.md against `apps/api/src/mcp.ts` - states,
+  `next_action`, `payer.mode`, cap `1000000` atomic, request-key error,
+  conflict error, amount/purpose validation all match the implementation.
+- `npx --yes markdownlint-cli2@0.18.1 ".agents/skills/oneshot-arc-payment/SKILL.md"` - 0 error(s).
+- `git ls-remote origin refs/heads/mcp-integration` - `b701bed` equals local
+  HEAD; push is a fast-forward.
+
+## External-doc findings
+
+- Agent-skill convention (`.agents/skills/<name>/SKILL.md`, YAML frontmatter
+  `name`/`description`) matches the repo's existing skills
+  (`oneshot-idempotency`, `oneshot-failure-injection`,
+  `sponsor-qualification`) and the user's local `~/.agents/skills/` layout.
+
+## Unresolved questions
+
+- None. Optional follow-up: add a "Download the agent skill" link on
+  `/docs/mcp` pointing at the raw GitHub skill file.
+
+## Git and PR state
+
+- Branch: `mcp-integration`
+- Base: `develop` at `94f2438` (PR #120 base is `mcp-integration -> develop`)
+- Commit: see Review gates / PR body for the exact SHA after push
+- PR: <https://github.com/SWOFART/OneShot/pull/120> (draft, updates in place)
+- CI: to be captured on the new head after push
+
+## Review gates
+
+- Gate A: PASS (in-session; a fresh `npx free-pi-cli` reviewer process cannot
+  start because free-pi allows one session per account and this session is the
+  active one — standing constraint documented in prior PRs #113/#114/#116/
+  #117/#118/#112). Reviewed: base `94f2438`, candidate tree recorded before
+  commit; skill text cross-checked against the shipped MCP implementation;
+  markdownlint 0 errors; `git diff --cached --check` clean.
+- Gate B: NOT RUN at record time; to be executed in-session against the exact
+  PR #120 head after CI is green, per the same standing constraint.
+
+## Handoff/next steps
+
+1. Commit, push `mcp-integration`, wait for required CI on the new head.
+2. Record Gate B PASS with head SHA/tree in PR #120 body.
+3. Optional follow-ups: `/docs/mcp` download link; raw-file link in repo README.

.agents/skills/oneshot-arc-payment/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: oneshot-arc-payment
+description: >
+  Pay a USDC recipient on Arc Testnet through the OneShot `arc_payment` MCP
+  tool: connect an MCP client with the operator-issued bearer token, create or
+  replay one durable payment intent, read the authoritative settlement state,
+  and verify the ArcScan proof. Use when the user asks to pay via OneShot, send
+  USDC on Arc, run the arc_payment MCP tool, or delegate an agent payment task.
+---
+
+# OneShot arc_payment MCP skill
+
+Pay once, safely, through OneShot. This skill is written for any agent
+(primary or delegated) whose MCP client is already connected to the OneShot
+MCP endpoint. It never handles keys: the payer is OneShot's policy-bound
+server wallet, and the bearer token lives only in the MCP client config.
+
+## Prerequisites (operator-provided, never invented)
+
+- MCP endpoint URL, e.g. `https://oneshot.kapustazh.dev/mcp` (Streamable HTTP).
+- `ONESHOT_MCP_BEARER_TOKEN` — configured in the MCP client as
+  `authorization: Bearer <token>`. It is a secret: never print, log, copy into
+  task prompts, or commit it.
+- One allowed `request_key` — the operator binds it to exactly one payment.
+- The per-payment cap (default 1000000 atomic = 1 USDC) is enforced
+  server-side; requests above it are rejected.
+
+If any of these is missing, stop and ask the operator. Do not guess values.
+
+## Tool contract: `arc_payment`
+
+Input (all fields required, strict):
+
+- `request_key` — the operator-issued key (this credential accepts only its
+  configured key; any other value is rejected).
+- `recipient` — `0x`-prefixed 40-hex EVM address on Arc Testnet.
+- `amount_usdc` — canonical decimal string, up to 6 decimals, greater than
+  zero (for example `1` or `0.25`; `1` USDC = `1000000` atomic units).
+- `purpose` — short non-secret payment purpose (max 256 chars).
+
+Output: `state` (`AUTHORIZING | READY | SUBMITTING | COMMITTED | FAILED_SAFE |
+UNKNOWN | REJECTED`), `replayed`, `payer.mode` (`SERVER_PRIVY`),
+`amount_atomic`, optional `settlement.transaction_hash` and
+`settlement.explorer_url`, and `next_action`
+(`WAIT | CHECK_STATUS | VIEW_PROOF | FIX_REQUEST`).
+
+## How to execute a payment
+
+1. Call `arc_payment` once with the operator's `request_key` and the exact
+   recipient, amount, and purpose the user approved.
+2. If `state` is `COMMITTED`, report `settlement.transaction_hash` and its
+   `explorer_url` (ArcScan). Done.
+3. If `state` is `SUBMITTING`/`AUTHORIZING`/`READY`, wait for the user or poll
+   by repeating the exact same call: it is a replay and returns the same
+   intent with fresh authoritative state. Never create a second key.
+4. If `state` is `UNKNOWN`, repeat the same call to check status. UNKNOWN is
+   not failure: it never justifies a replacement payment or a new key.
+5. If the tool returns the conflict error ("already belongs to a different
+   payment"), the key was reused with changed fields. Stop, report the
+   conflict, and ask the operator for the original fields or a new key.
+6. If `state` is `FAILED_SAFE` or `REJECTED`, report it and stop. Do not retry
+   with a different key or amount.
+
+## Delegating (outsourcing) the payment to another agent
+
+- Hand the delegate only the task arguments: endpoint URL, `request_key`,
+  `recipient`, `amount_usdc`, `purpose`, and this skill.
+- The delegate must use its own MCP client configuration; the bearer token
+  must not travel through prompts, task payloads, logs, or screenshots.
+- One request_key funds exactly one intent. To parallelize, ask the operator
+  for one key per payment; never derive or mutate keys.
+- The delegate reports back the authoritative `state` plus the ArcScan proof
+  for `COMMITTED`, or the exact tool error. "It probably went through" is not
+  a report.
+
+## References
+
+- Walkthrough: `docs/MCP_ARC_PAYMENT.md` in the OneShot repository.
+- Human-readable page: `https://oneshot.kapustazh.dev/docs/mcp`.
+- Install: copy this folder into the agent's skills directory, or add the
+  GitHub source `SWOFART/OneShot` with skill path
+  `.agents/skills/oneshot-arc-payment/SKILL.md`.

.env.example

@@ -13,6 +13,15 @@ ONESHOT_WORKSPACE_ID=team-testnet-workspace
 ONESHOT_API_RATE_LIMIT_MAX_REQUESTS=60
 ONESHOT_API_RATE_LIMIT_WINDOW_MS=60000
 
+# One-tool MCP demo. The bearer is accepted only at /mcp. The configured
+# request key makes this deployment a literal one-intent demo; identical calls
+# replay the same durable payment and any other key is denied.
+# ONESHOT_MCP_BEARER_TOKEN=<random-secret-at-least-32-characters>
+# ONESHOT_MCP_REQUEST_KEY=<one-stable-demo-request-key>
+# ONESHOT_MCP_PAYER_ADDRESS=0x<40-hex-privy-server-wallet-address>
+# ONESHOT_MCP_MAX_AMOUNT_ATOMIC=1000000
+# ONESHOT_MCP_WAIT_MS=2500
+
 # Production worker effect boundary. Public identifiers are placeholders;
 # secrets must be injected by the deployment secret store, never committed.
 ONESHOT_ARC_PROFILE=arc-testnet

README.md

@@ -315,6 +315,7 @@ plus explicit human authorization.
 | ------------------------------------------------------------------------ | -------------------------------------------------------- |
 | [`plan.md`](plan.md)                                                     | Product plan, scope, and delivery gates                  |
 | [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md)             | Domain model and boundaries                              |
+| [`docs/MCP_ARC_PAYMENT.md`](docs/MCP_ARC_PAYMENT.md)                     | One-tool MCP deployment and live walkthrough             |
 | [`docs/RECOVERY_HARDENING.md`](docs/RECOVERY_HARDENING.md)               | Recovery, runtime, authentication, and metrics contracts |
 | [`milestones/CONTRACTS.md`](milestones/CONTRACTS.md)                     | Frozen v1 contract pack                                  |
 | [`docs/settlement/`](docs/settlement/)                                   | Settlement config, provider setup, live evidence         |