Verified Support Agent

A real AI agent, built with the Claude Agent SDK, whose only path to a backend is through an MCP server secured with KYA-OS (the open agentic identity and delegation standard, donated to the Decentralized Identity Foundation by Vouched).

The scenario mirrors Vouched's own recurring example: a support agent that can process a $50 refund automatically but needs a human to approve anything larger. Everything here is real - a real Ed25519-signed cryptographic identity, a real W3C Delegation Credential, a real consent HTTP server issuing it, and a real agent making the tool calls. The only thing that's mocked is the order data (see "Why mocked" below).

Agent calls issue_refund($30)  -> executes immediately, proof attached
Agent calls issue_refund($500) -> needs_authorization -> human approves at a real URL -> agent retries -> succeeds

Why this exists

AI agents now act on behalf of users - checking order status, issuing refunds, moving money - using credentials that make them indistinguishable from the human they're acting for. A session cookie collapses three separate questions into one indistinguishable HTTP request: who is actually acting, on whose authority, and is this specific action inside that authority. KYA-OS answers those three questions separately, so low-stakes actions can be fully automated (with a signed proof of who did them) and high-stakes actions require the agent to prove it was delegated that specific authority, often with a live human consent step.

Vouched's own materials return to two examples repeatedly: a support/refund agent ("process a $50 refund automatically but need approval above $5,000") and a travel-booking agent ("view flight status but not book flights without approval"). This repo builds the first one for real, end to end.

Related MCP server: Commerce Operations MCP Server

Quick start

npm install
npm run verify   # deterministic, no LLM needed - proves the whole lifecycle works
npm run agent    # the real thing - a live Claude Agent SDK agent driving 3 scripted turns

npm run verify runs src/verify-lifecycle.ts: a self-contained script that exercises every part of the lifecycle in one process (proof generation, proof verification, a deliberate tamper test that must fail, the full needs_authorization -> real consent-server approval -> auto-applied retry -> success loop) and prints PASS/FAIL per check. No API key needed - it never calls an LLM.

npm run agent runs src/agent.ts: a real agent, built with the Claude Agent SDK, connected to src/server.ts as an MCP tool source over stdio. It drives three prompts - checking an order, issuing a $30 refund, and issuing a $500 refund - and stops at the authorization link on the third one, on purpose. That pause is the point: the agent never sees a proof or a credential, it just sees a tool that sometimes asks it to relay an authorization link to a human. Needs ANTHROPIC_API_KEY set (or an authenticated claude CLI session).

What's in each file

Adapt this to your own MCP server

The pattern in kya-tools.ts generalizes to any MCP server:

1. Wrap your server's identity: createKyaOsMiddleware({ identity, session: {...}, autoSession: true }, crypto).

2. Classify each tool. Read-only or low-stakes: kyaos.wrapWithProof('tool_name', handler) - attributable via a signed proof, not gated. High-stakes: kyaos.wrapWithDelegation('tool_name', { scopeId, consentUrl, formatChallenge }, kyaos.wrapWithProof('tool_name', handler)) - blocked until a delegation credential with that scope is presented.

3. Point consentUrl at your own authorization page, or reuse consent-server.ts and public/consent.html as-is.

4. Wrap the delegation-gated handler in formatAsConsentLink() (see kya-tools.ts) so an approved credential is auto-applied on the caller's retry - nobody ever pastes a credential back by hand.

That's the shape of an integration guide, not just evidence this one demo runs.

Why mocked, not a real integration

check_order_status and issue_refund operate on a small fixed in-memory dataset - no real orders, no real customers, no real payment processor, nothing PCI/PII-relevant. The thing being demonstrated here is KYA-OS identity and delegation, not e-commerce or payments engineering, and a real integration would add data-handling and security surface for zero benefit to that story.

What this deliberately doesn't cover yet

• Checkpoint (Vouched's agent-traffic-detection layer) - it has a genuine free self-serve signup, but that's a personal account-creation step outside the scope of this repo.

• Multiple frameworks - Vouched's own docs list Next.js, Express, Python, HTML, and direct API. This repo is Node/TypeScript only; an Express variant is a natural next step given @kya-os/mcp's API is transport-agnostic.

• IdentiClaw / KnowThat.ai - the other two layers of Vouched's KYA suite; their public docs are still thin.

Built on

@kya-os/mcp - MIT-licensed reference implementation of KYA-OS for the Model Context Protocol, donated by Vouched to the Decentralized Identity Foundation's Trusted AI Agents Working Group.