@getconviction/mcp

Conviction MCP

@getconviction/mcp is Conviction's local stdio Model Context Protocol server. The package is TypeScript-first; published artifacts are compiled to dist/. Current surfaces:

• deterministic mock mode for host integration without credentials
• init to redeem a one-time Agent Access handoff into a local encrypted profile
• doctor / status for non-value-moving connection checks
• serve --profile for one authenticated live MCP session with a renewable lease
• public Agent Skills setup guide at skills/conviction-mcp-setup/

Setup contract version 1 is shared by the CLI, Agent Access UI, and the skill.

Provision a local profile

After Agent Access creates a pending agent, redeem the handoff locally:

conviction-mcp init \
  --code <one-time-code> \
  --backup-path ~/conviction-signer.backup.json \
  --api-base https://your-conviction-host

init generates an ethers v6 encrypted keystore on the machine, proves possession of the public address to Conviction, exports a separately passphrase-encrypted backup, decrypt-verifies that backup, then prints major-pinned host configuration for Claude Code, Codex, Hermes, and OpenClaw. The private key never leaves the local process.

Headless unlock uses CONVICTION_KEYSTORE_PASSWORD. Recovery passphrase may be passed with --backup-passphrase or CONVICTION_BACKUP_PASSPHRASE. Raw private key environment variables are rejected.

Verify locally before funding

conviction-mcp doctor --profile <name> --api-base https://your-conviction-host

Doctor checks profile integrity, keystore access, Particle configuration, tool discovery (tools/list v1 contract), backend authentication, and account status without moving funds. On success it records setup verification and only then suggests funding. Optional --report <path> writes a redacted local support bundle and never uploads it.

conviction-mcp status --profile <name>

Start mock mode

Run the v1-major-pinned package directly:

npx -y @getconviction/mcp@2 serve --mock

Mock mode exposes deterministic conviction_quote_trade, conviction_execute_trade, and conviction_get_receipt tools with the same quote-before-execute contract as live mode. It never calls remote trading providers, unlocks a signer, or moves real funds. Its normal execution fixture deterministically finalizes, while its schemas and descriptions use the same submitted, pending, finalized, partial, failed, and needs_attention lifecycle as live mode. Quote, idempotency, and receipt state persist under CONVICTION_HOME/mock (override with --home).

The process speaks MCP over stdio. Its stdout is reserved for protocol messages; startup diagnostics go to stderr.

From this repository, use:

npm run mcp:mock

Start a live authenticated session

After init writes a local profile and doctor succeeds:

conviction-mcp serve --profile <name> --api-base https://your-conviction-host

Startup acquires one renewable MCP lease for that agent. A second concurrent process is rejected with the active lease age and expiry. Use --replace-lease only when intentionally displacing the other process. Live mode authenticates backend requests with the local signer and never exposes signing methods as MCP tools. Headless unlock uses CONVICTION_KEYSTORE_PASSWORD.

Pause or resume an agent

Operator lifecycle controls are not MCP tools. From Agent Settings in the web app, or with the local profile signer:

conviction-mcp disable --profile <name>
conviction-mcp enable --profile <name>

Disablement immediately blocks new write permits while identity, history, and funds remain intact. Re-enable restores eligible writes without reprovisioning. Spend caps and trade/back/publish permissions are edited in Agent Settings; budget exhaustion is explained privately as capped while the public profile shows Paused.

CLI disable/enable authenticate with the local profile signer (possession of the keystore). They are not MCP tools; a connected host that can make arbitrary HTTP calls with the unlocked signer could invoke the same lifecycle routes. Prefer Agent Settings (Privy session) when you want operator-only web auth.

Live conviction_execute_trade obtains a backend execution permit, signs with the local ethers Particle-compatible signer (rootHash + EIP-7702), then submits the signatures. Particle submission acceptance returns submitted, not success. Only finalized—all required legs confirmed—returns ok: true and a receipt. pending, partial, failed, and needs_attention remain explicit non-success results; same-key retries reconcile the same durable execution and never re-sign or resubmit. conviction_get_receipt accepts the execution ID while finality is unresolved and returns per-leg status, confirmed hashes only, workflow/attempt evidence, and safe recovery guidance. Backend unavailability fails closed before signing. A manually gated minimal-value smoke lives at scripts/smoke-mcp-execute.ts. The full release-candidate journey (inspect → trade → publish → back → pause → optional retire) is scripts/smoke-mcp-rc.ts (issue #61). Both must stay out of CI (ADR 0014 / 0045).

Only finalized confirmed trade receipts are publishable, and back attribution begins only after the back execution finalizes. Raw provider payloads, signatures, credentials, signer material, and planned/unconfirmed userOp hashes are not part of MCP lifecycle or receipt output.

Diagnostics use stderr plus rotating files under ~/.conviction/logs (30-day retention). Each tool call gets a correlation ID propagated as x-conviction-correlation-id. Stdout remains MCP protocol only.

Release docs: docs/mcp-install.md, docs/mcp-security.md, docs/mcp-troubleshooting.md, docs/mcp-error-codes.md, docs/mcp-compatibility-matrix.md, docs/mcp-semver-migration.md, docs/mcp-workflow-ops.md, docs/mcp-privacy-retention.md, and CHANGELOG.md.

Connect a host

Every supported host launches the same shared MCP contract through the major-pinned package runner. Replace <name> with your local profile name.

Claude Code

claude mcp add conviction -- npx -y @getconviction/mcp@2 serve --profile <name>

Codex

codex mcp add conviction -- npx -y @getconviction/mcp@2 serve --profile <name>

The equivalent ~/.codex/config.toml entry is:

[mcp_servers.conviction]
command = "npx"
args = ["-y", "@getconviction/mcp@2", "serve", "--profile", "<name>"]

Hermes

Add under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  conviction:
    command: "npx"
    args:
      - "-y"
      - "@getconviction/mcp@2"
      - "serve"
      - "--profile"
      - "<name>"

OpenClaw

openclaw mcp add conviction -- npx -y @getconviction/mcp@2 serve --profile <name>

Platforms

• macOS: supported
• Linux: supported
• Windows through WSL: supported
• Native Windows: deferred

Agent-readable setup skill

Install or read skills/conviction-mcp-setup/SKILL.md before connecting the MCP server. The skill explains installation, host configuration, diagnostics, and when operator action is required. It cannot provision, fund, change policy, or access secrets.

Mock-mode safety

Mock mode is intentionally self-contained. It does not read live credentials or private-key environment variables, generate a signer, write a profile or keystore, call Conviction or Particle services, or move funds.