{
  "markdown": "# agent-services-mcp\n\nA single **thin MCP (Model Context Protocol) server** that exposes three existing\nservices as discoverable tools, so AI agents and MCP-compatible clients can find\nand use them through one connection:\n\n- **[provenance-receipts](https://github.com/Gareth1953/provenance-receipts)** — certifies content **origin**;\n  returns an Ed25519-signed receipt.\n- **[quality-gate](https://github.com/Gareth1953/quality-gate)** — scores content **quality** against a\n  published rubric; returns an Ed25519-signed score receipt.\n- **agent-action-audit** — signs a **tamper-evident audit receipt** for an action an\n  agent took (agent accountability); returns an Ed25519-signed audit receipt.\n\n> **It is a thin wrapper.** Every tool forwards an HTTP call to the underlying\n> Worker and returns its response verbatim. It does **not** reimplement signing,\n> scoring, or payment logic — those live in the underlying services. The honesty\n> about what each service proves carries through to the tool descriptions.\n\n## Quickstart — your first (free) call in ~2 minutes\n\n```bash\nnpm install && npm run build\nnode examples/free-call.mjs       # connects to the LIVE services and calls a free tool\n```\n\n`examples/free-call.mjs` runs an MCP client against this server (pointed at the live\ndeployments) and calls `get_quality_rubric` and `verify_audit` — both **free**, no\nwallet needed. To wire the server into an MCP client (Claude Desktop / Claude Code\nstyle), see **Connecting an MCP client** below.\n\n**Free vs paid at a glance:** `verify_provenance`, `verify_quality`, `verify_audit`,\nand `get_quality_rubric` are **free**. `certify_provenance`, `score_quality`, and\n`audit_action` are **paid** (an x402 USDC micropayment on Base) — see **Calling paid\ntools** for the two-step payment flow and a working example.\n\n## What the wrapped services prove (and do not)\n\n- **Provenance:** proves the content is unmodified (SHA-256 hash) and the receipt\n  was issued by the service's key. The `generator_metadata` is **caller-attested**\n  — it proves you *claimed* it, not that a specific model ran. Not AI-detection,\n  not a truth guarantee.\n- **Quality:** a reproducible score **against the published rubric** (clarity,\n  completeness, internal consistency, obvious-error freedom). **Not** absolute\n  truth, **not** an external standard, **not** a fact-check. Read the rubric via\n  the `get_quality_rubric` tool.\n- **Audit:** proves the action **record** is genuine (issued by the service's key)\n  and **unaltered since issue** (tamper-evident). The `action`, `actor_metadata`,\n  and `context` are **caller-attested** — it proves you *claimed* this record, not\n  that the agent's claim is true. An accountability/audit tool, **not** a\n  lie-detector.\n\n## Tools\n\n| Tool                 | Forwards to                              | Paid?      | Input |\n| -------------------- | ---------------------------------------- | ---------- | ----- |\n| `certify_provenance` | provenance-receipts `POST /v1/certify`   | yes (x402) | `content` (string), `generator_metadata` (object, optional) |\n| `verify_provenance`  | provenance-receipts `POST /v1/verify`    | no         | `content` (string), `receipt` (object) |\n| `score_quality`      | quality-gate `POST /v1/score`            | yes (x402) | `content` (string), `rubric_version` (string, optional), `target_score` (number 0–100, optional) |\n| `verify_quality`     | quality-gate `POST /v1/verify`           | no         | `content` (string), `receipt` (object) |\n| `get_quality_rubric` | quality-gate `GET /v1/rubric`            | no         | none |\n| `audit_action`       | agent-action-audit `POST /v1/audit`      | yes (x402) | `action` (string), `actor_metadata` (object), `context` (object, optional) |\n| `verify_audit`       | agent-action-audit `POST /v1/verify`     | no         | `action` (string), `actor_metadata` (object), `context` (object, optional), `receipt` (object) |\n\nFull descriptions and Zod input/output schemas: [`src/tools.ts`](src/tools.ts).\nEach tool returns the service's raw JSON (or markdown, for the rubric) as text; the\n`verify_*` and `score_quality` tools **also** declare an `outputSchema` and return\nparsed **`structuredContent`** you can read directly (e.g. `result.structuredContent.valid`).\nA non-2xx response (including a `402 Payment Required`) is surfaced with\n`isError: true` and the body preserved — for a `402` the wrapper prepends a short,\nactionable note on how to pay. The three **paid** tools also accept an optional\n**`x_payment`** input (the x402 X-PAYMENT token) to settle payment through the\nwrapper — see **Calling paid tools**.\n\n## Configuration\n\nThe three service URLs are environment-configurable (no secrets — just base URLs):\n\n| Env var            | Live (deployed)                                          | Local dev fallback        |\n| ------------------ | -------------------------------------------------------- | ------------------------- |\n| `PROVENANCE_URL`   | `https://provenance-receipts.gpmiddleton71.workers.dev`  | `http://localhost:8787`   |\n| `QUALITY_GATE_URL` | `https://quality-gate.gpmiddleton71.workers.dev`         | `http://localhost:8788`   |\n| `AUDIT_URL`        | `https://agent-action-audit.gpmiddleton71.workers.dev`   | `http://localhost:8789`   |\n\n`.env.example` and the client config below point at the **live** deployments. If\nthe vars are unset, the server falls back to localhost for local `wrangler dev`\n(the Workers default to `:8787`, so run quality-gate on `:8788` and\nagent-action-audit on `:8789` to avoid clashes).\n\n> Against the live services, the **paid** tools (`certify_provenance`,\n> `score_quality`, `audit_action`) require x402 — this wrapper forwards the request\n> and holds no wallet, so without an `X-PAYMENT` they return a `402` (the payment\n> requirements) surfaced as `isError`. The free tools work as normal.\n\n## Calling paid tools (x402)\n\nThe three paid tools require an x402 micropayment (USDC on Base mainnet). The wrapper\n**holds no wallet** — it never spends on your behalf — so paying is a two-step flow:\n\n1. **Call the tool with no `x_payment`.** You get back a `402` whose body is the x402\n   payment **requirements** (network, asset, amount, `payTo`). The wrapper prepends a\n   one-line note explaining what to do next.\n2. **Build an x402 `X-PAYMENT` token** from those requirements with an x402 client +\n   a funded wallet, then **call the tool again with that token in the `x_payment`\n   input.** The wrapper forwards it as the `X-PAYMENT` header; the underlying service\n   verifies, settles, and returns the signed receipt.\n\nEasiest path to a *working* paid call — let an x402 client settle for you against the\nunderlying service directly:\n\n```bash\nnpm install x402-fetch\nBUYER_PRIVATE_KEY=0x...  node examples/paid-call.mjs\n```\n\n`examples/paid-call.mjs` uses `x402-fetch` + a **throwaway** Base-mainnet wallet\n(holding a little real USDC) to pay for and call `audit_action`. ~$0.01 USDC moves\nbuyer → the service's `payTo`, gasless (the facilitator pays gas). **Real money — use\na disposable key with a few cents only.** The same applies to `certify_provenance`\nand `score_quality`.\n\n## Quickstart (local)\n\n```bash\n# 1. Build the MCP server\nnpm install\nnpm run build            # -> dist/index.js\n\n# 2. In separate terminals, run the three services (free; payments off)\n#    (provenance-receipts) npm run dev                 # http://localhost:8787\n#    (quality-gate)        npx wrangler dev --port 8788 # http://localhost:8788\n#    (agent-action-audit)  npx wrangler dev --port 8789 # http://localhost:8789\n\n# 3a. Smoke-test the free tool paths through an MCP stdio client\nnode scripts/test-client.mjs\n\n# 3b. (optional, costs ~$0.012) prove the paid score_quality path end-to-end\nnode scripts/test-score.mjs\n\n# 3c. Smoke-test the wrapper against the LIVE deployed services (free — the\n#     paid tools return a forwarded 402; no payment, no scoring call)\nnode scripts/test-live.mjs\n```\n\n`scripts/test-client.mjs` exercises the free tools locally; `scripts/test-score.mjs`\nmakes one real Anthropic scoring call through `score_quality`;\n`scripts/test-live.mjs` points the wrapper at the deployed workers.dev URLs and\nasserts the free tools work and the paid tools forward the x402 `402`.\n\n## Connecting an MCP client (stdio)\n\nThis server speaks MCP over **stdio** (stdin/stdout). Any MCP client launches it\nas a subprocess. Example for a Claude Desktop / Claude Code style\n`mcpServers` config:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-services\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\Gareth\\\\agent-services-mcp\\\\dist\\\\index.js\"],\n      \"env\": {\n        \"PROVENANCE_URL\": \"https://provenance-receipts.gpmiddleton71.workers.dev\",\n        \"QUALITY_GATE_URL\": \"https://quality-gate.gpmiddleton71.workers.dev\",\n        \"AUDIT_URL\": \"https://agent-action-audit.gpmiddleton71.workers.dev\"\n      }\n    }\n  }\n}\n```\n\n- Run `npm run build` first so `dist/index.js` exists.\n- The client connects, calls `tools/list` (it will see the 7 tools above), and\n  invokes them via `tools/call`.\n- The underlying services must be reachable at the configured URLs when a tool is\n  called.\n- Logs go to **stderr**; stdout is reserved for the MCP protocol.\n\nProgrammatically, connect with the SDK's `Client` + `StdioClientTransport`\n(`command: \"node\"`, `args: [\"dist/index.js\"]`) — see `scripts/test-client.mjs`.\n\n## x402 payments (forwarded, not handled here)\n\nThe paid endpoints (`/v1/certify`, `/v1/score`, `/v1/audit`) are gated by\n[x402](https://github.com/coinbase/x402) on the underlying services. This wrapper\n**forwards** requests and does not hold a wallet. If a service has payments\nenabled and no valid `X-PAYMENT` is supplied, it returns `402` with the payment\nrequirements — the wrapper surfaces that as `isError` with the requirements body\nintact. Settling a payment (signing an x402 authorization) is the client's\nresponsibility against the underlying service. See each service's `README.md` /\n`docs/API.md` for the x402 details. **Base Sepolia testnet only — no mainnet.**\n\n## Verifying receipts independently\n\nThe receipts returned by `certify_provenance`, `score_quality`, and `audit_action`\nare Ed25519-signed and verifiable **without trusting any of these services** —\nre-hash the content/record and check the signature against the service's public\nkey. Each service ships a runnable independent verifier and recipe: see\n[provenance-receipts/docs/VERIFYING.md](https://github.com/Gareth1953/provenance-receipts/blob/main/docs/VERIFYING.md),\n[quality-gate/docs/VERIFYING.md](https://github.com/Gareth1953/quality-gate/blob/main/docs/VERIFYING.md),\nand agent-action-audit's `docs/VERIFYING.md`.\n\n## Build status\n\n- [x] **Step 1 — skeleton + tool definitions** (`src/tools.ts`)\n- [x] **Step 2 — tool handlers (HTTP forwarding) + local smoke test**\n- [x] **Step 3 — README: what it is, the tools, and how an MCP client connects**\n- [x] **Live — pointed at the deployed services** (`*.gpmiddleton71.workers.dev`)\n      and verified end-to-end via `scripts/test-live.mjs`: free tools work; paid\n      tools forward the x402 `402`.\n\nAll seven tool paths verified against the live deployments (including one paid\n`score_quality` call end-to-end through the wrapper); the paid tools\n(`certify_provenance`, `score_quality`, `audit_action`) forward the x402 `402`.\n\n## Stack\n\n- Official MCP SDK: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)\n  v1.29.0 (TypeScript), stdio transport, [`zod`](https://www.npmjs.com/package/zod)\n  input schemas.\n- Node ESM + TypeScript (`tsc` → `dist/`).\n\n## Project layout\n\n```\nagent-services-mcp/\n├── src/\n│   ├── index.ts     # MCP server: registers tools, forwards HTTP, stdio transport\n│   └── tools.ts     # the 7 tool definitions (names, descriptions, Zod schemas)\n├── scripts/\n│   ├── test-client.mjs  # MCP stdio client — free tool smoke test (local)\n│   ├── test-score.mjs   # MCP stdio client — one paid score_quality e2e check\n│   └── test-live.mjs    # MCP stdio client — against the live deployed services\n├── package.json\n├── tsconfig.json\n├── .gitignore\n└── .env.example     # PROVENANCE_URL, QUALITY_GATE_URL, AUDIT_URL\n```\n",
  "bytes": 12177,
  "sha": "efb30c8b3b49e7f288d7485803a1848cee01c15447a1d579c0b9830efa199c19",
  "repo_slug": "gareth1953/agent-services-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gareth1953_agent_services_mcp_747797a7/readme"
}