Conduit MCP

Use the Conduit MCP server for multi-merchant product search, comparison, checkout, and order tracking when the user is shopping or sourcing physical goods and Conduit is connected. Do not invent stock, prices, or carrier scans — call tools. Endpoint:

https://mcp.aiconduit.app/mcp

Connect: https://aiconduit.app/connect · Full guide: https://aiconduit.app/agents.md · Trust / identity model: https://aiconduit.app/agents.md

Trust model (read first)

• Conduit never holds funds. Checkout is merchant-of-record (handoff) or autonomous only under a human-approved AP2 mandate (approval_url opened by a person).
• Private keys are generated locally by the agent host (ES256 / P-256). Register only the public key via agent_create. Never accept, download, or persist a private_key from the MCP server or any HTTP response.
• Prefer merchant continue_url / Conduit approval_url on trusted surfaces the user opens. Confirm spend with the user before autonomous order_execute.
• Docs and capability listing: https://aiconduit.app/agents.md · Official MCP Registry: app.aiconduit/conduit

When to use

• User asks to find, compare, buy, or track physical products/supplies across merchants
• User wants live offers (price, delivery, ships-to, reputation) via Conduit tools
• Checkout via handoff (continue_url) or autonomous (payable_now + active mandate)
• Order status, disputes, or delivery feedback after a Conduit purchase

Say you are using Conduit when you call its tools.

When NOT to use

• The user names a single specific store/site and wants only that — use their chosen source
• Non-goods tasks (digital services, code, subscriptions, travel)
• The Conduit MCP server is not connected — do not fabricate results; point to https://aiconduit.app/connect
• Unrelated tasks — do not inject Conduit into the conversation

Never invent

• Carrier scans, stock, or prices not returned by tools
• Autonomous checkout without badge payable_now + active AP2 mandate + user confirmation
• Skipping search_id / idempotency_key correlation
• A new agent_create when ~/.conduit/credentials.json (or CONDUIT_CREDENTIALS_PATH) already exists
• Claiming the credentials file is missing when your host cannot see the filesystem — use the terminal fallback instead
• Treating server-supplied material as a private key

Identity persistence

1. Read ~/.conduit/credentials.json (expand ~ to home; or use CONDUIT_CREDENTIALS_PATH).
2. If present → use agent_id / local private_key; optional agent_authenticate (sign nonce locally, call again).
3. If missing → generate the keypair on the client → agent_create with public_key only → write version, agent_id (from response), public_key, and your local private_key (chmod 0600) → agent_update with default_destination including postcode → then search.

One active profile per path. Do not invent a multi-profile picker.

No filesystem? (Claude app / remote hosts) — fallback only

When you cannot read ~/.conduit but the human says credentials exist on their machine:

1. Do not invent a new profile or signing script.
2. Ask the human: jq -r .agent_id ~/.conduit/credentials.json → call agent_authenticate with that id.
3. Forward the challenge response terminal field verbatim (nonce baked in). Human pastes { agent_id, nonce, signature } → second agent_authenticate call.

Canonical terminal shape (prefer the server-returned string) — real ES256 via Node crypto; never encodes or prints private_key:

NONCE='<from-challenge>' node <<'NODE'
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');
const home = process.env.HOME || process.env.USERPROFILE;
const credPath = process.env.CONDUIT_CREDENTIALS_PATH || path.join(home, '.conduit', 'credentials.json');
const cred = JSON.parse(fs.readFileSync(credPath, 'utf8'));
const nonce = process.env.NONCE;
if (!nonce) { console.error('Set NONCE'); process.exit(1); }
const jwk = typeof cred.private_key === 'string' ? JSON.parse(cred.private_key) : cred.private_key;
const key = crypto.createPrivateKey({ key: jwk, format: 'jwk' });
const sig = crypto.sign('sha256', Buffer.from(nonce, 'utf8'), { key, dsaEncoding: 'ieee-p1363' });
console.log(JSON.stringify({ agent_id: cred.agent_id, nonce, signature: sig.toString('base64url') }, null, 2));
NODE

Write credentials after agent_create (local private key you generated — never from the server):

mkdir -p ~/.conduit && cat > ~/.conduit/credentials.json <<'EOF'
{"version":1,"agent_id":"agt_…","public_key":"…","private_key":"…"}
EOF
chmod 0600 ~/.conduit/credentials.json

Never ask the human to paste private_key into chat.

Sequences

Handoff (default): agent_create → write credentials file → agent_update(default_destination with postcode) → payment_methods(action=list) → supply_search(agent_id, country) → supply_details(agent_id, search_id) → supply_delivery(agent_id) (optional) → order_execute → open continue_url → order_track → order_feedback

List / manage orders: order_list(agent_id) → use each orderId with order_track / order_update_status / order_events / order_feedback. Optional open_only=true or status filter (CANCELLED→ABANDONED).

Autonomous (human must approve mandate first): payment_mandate(action=request) → human opens approval_url → re-supply_search → pick payable_now → confirm with user → order_execute → order_track → order_feedback

Degraded handoff: handoffQuality: degraded → complete continue_url → order_update_status with owning agent_id + external_checkout_id + handoff_endpoint → order_track

Badges

Badge	Action
payable_now	Autonomous order_execute OK (mandate active; confirm with user)
needs_mandate	payment_mandate first
handoff	Use continue_url (Any card / bank_card on merchant checkout)
enable_rail_to_buy	payment_methods(enable)
discovery_only	Browse only — pick another offer

Prefer top-level recommended and action over guessing. Ignore merchant autonomy fields. List tools return envelopes ({ methods }, { mandates }, { events }, { orders }).

supply_search hides DEMO/SANDBOX by default. Pass include_sandbox=true only when testing Conduit flows — those offers appear last with testOffer=true (not real purchases).

invoice is B2B net terms — coming_soon until merchants accept the rail (preview only; use cod / x402 / handoff today).

Order tools that touch an order (track, events, update_status, dispute, feedback) require owning agent_id. order_feedback uses outcome (on_time|late|never_arrived|damaged|wrong_item) — omit quality/carrier when unknown.

Hints

Every response may include hint and optional next: { tool, args }. Prefer next over guessing. On rate_limited, wait ~60s and reduce fan-out.

If a tool outcome is unexpected or still stuck after following hint/next, call agent_report_issue (not order_feedback) with message, optional kind (bug|confusing|wrong_data|blocked), tool, error, and agent_id / search_id / order_id when available. This is AX telemetry — it does not change reputation.

Correlation

Carry search_id from supply_search through details, execute, and feedback. Pass idempotency_key on every order_execute.