Vyana MCP (agent-side)

Installs in the developer's coding agent (Claude Code, Codex, Cursor, Antigravity…) and runs locally in their terminal. It is the only place the device's private signing key is touched — the agent itself never holds it.

The agent calls vyana_provision → the MCP server signs the request with the paired device key → the broker runs the verify chain, calls the merchant, and returns a signed Credential Capsule → the credentials are written into the project's .env.

What this project implements

| Piece | Where | Status | |---|---|---| | CLI: install / signup / pair / provision / doctor / serve | bin/vyana.mjs (+ bin/lib/*.mjs) | ✅ real | | MCP server (stdio) | src/server.ts | ✅ serves tools | | Tools: vyana_provision, vyana_status | src/tools.ts | ✅ real (signs + calls broker) | | Device key + signing | bin/lib/{config,sign}.mjs | ✅ Ed25519 key in ~/.vyana (0600 file; OS-keychain swap noted) | | ASP objects + crypto | lib/protocol/ | ✅ vendored copy |

Use it

# from the repo (no publish needed): commands are `node bin/vyana.mjs <cmd>`
npx vyana-mcp install                             # auto-detect installed tools and write MCP config
npx vyana-mcp install --setup                     # install, then open signup and pair this device
npx vyana-mcp install [claude|cursor|codex|antigravity|all]
npx vyana-mcp signup                              # opens broker onboarding (KYC + authenticator + consent)
npx vyana-mcp pair                                # generate device key, confirm in browser, store bearer
npx vyana-mcp provision nimbus-db free            # sign + provision now; writes creds to .env.local
npx vyana-mcp doctor                              # key / pairing / broker checks

After install, restart your agent and ask it to provision — it calls vyana_provision, which uses the same signed path as the CLI command.

Config: VYANA_BROKER_ORIGIN (default https://vyana-broker.vercel.app — the hosted broker; a localhost default would silently send bearer tokens to any service on :3000, so it's never used as a fallback), VYANA_HOME (default ~/.vyana), VYANA_FETCH_TIMEOUT_MS (default 60000 — bump if your broker is on a slow tunnel or cold-starting serverless). State lives in ~/.vyana/{device.pem,config.json}; each knob can also be set persistently by adding a key to config.json (broker, fetch_timeout_ms).

Localhost is refused by default, even when set explicitly. Broker developers opt in per dev clone with VYANA_ALLOW_LOCALHOST=1 (or --allow-localhost on CLI commands). The opt-in is ignored in published npm builds (detected by the file path being under node_modules/) — a published vyana-mcp on an end user's machine refuses every localhost connection regardless of env vars or flags. So you can iterate against npm run dev locally, but a published install will never silently (or noisily) talk to anything on the user's loopback.

How install wires each agent

| Agent | File written | Shape | |---|---|---| | Claude Code | ./.mcp.json (project) | mcpServers.vyana | | Cursor | ~/.cursor/mcp.json | mcpServers.vyana | | Codex | ~/.codex/config.toml | [mcp_servers.vyana] | | Antigravity | ~/.antigravity/mcp_settings.json | mcpServers.vyana |

With no target, install auto-detects available tools by checking known config directories and commands on PATH. Use install all to write every supported config even if the tool is not detected. Each entry runs npx -y vyana-mcp@beta serve, which launches the MCP server over stdio.

Security-critical invariants

• The Ed25519 private key never leaves this machine and never goes to the agent or broker. Only the public key (at pairing) and signatures cross the wire.
• The device's public key is bound to the user's account in the browser pairing step; the broker's signature verify layer rejects anything else.
• The user's raw message is captured verbatim and sent for the broker's intent layer, so a prompt-injected agent can't silently change the ask.

lib/protocol/ is a vendored copy shared by contract with broker/, merchant-sample/, and merchant-stock/; keep it byte-identical. bin/lib/sign.mjs mirrors its canonical-payload form for the no-build CLI.