---
name: conduit
description: >-
  Find, compare, buy, and track physical products across merchants through the
  Conduit agentic-commerce MCP when it is connected and the user wants shopping
  or procurement help. Covers offer badges (payable_now, handoff, needs_mandate),
  local ES256 identity (private key never leaves the machine), human-approved
  AP2 mandates for autonomous checkout, and degraded-handoff recovery.
---

# 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 `create_agent_profile`. **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 `execute_order`.
- 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 `create_agent_profile` 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 `authenticate_agent` (sign nonce locally, call again).
3. If missing → **generate the keypair on the client** → `create_agent_profile` with **public_key only** → write `version`, `agent_id` (from response), `public_key`, and **your local** `private_key` (`chmod 0600`) → `update_agent_profile` 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 `authenticate_agent` with that id.
3. Forward the challenge response `terminal` field **verbatim** (nonce baked in). Human pastes `{ agent_id, nonce, signature }` → second `authenticate_agent` call.

Canonical `terminal` shape (prefer the server-returned string) — real ES256 via Node `crypto`; never encodes or prints `private_key`:
```bash
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 `create_agent_profile`** (local private key you generated — never from the server):
```bash
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):**
`create_agent_profile` → write credentials file → `update_agent_profile(default_destination with postcode)` → `payment_methods(list)` → `search_supply(agent_id, country)` → `get_supply_details(agent_id, search_id)` → `get_delivery_estimate(agent_id)` (optional) → `execute_order` → open `continue_url` → `track_order` → `submit_feedback`

**List / manage orders:**
`list_orders(agent_id)` → use each `orderId` with `track_order` / `update_order_status` / `get_order_events` / `submit_feedback`. Optional `open_only=true` or `status` filter (CANCELLED→ABANDONED).

**Autonomous (human must approve mandate first):**
`request_payment_mandate` → human opens `approval_url` → re-`search_supply` → pick `payable_now` → confirm with user → `execute_order` → `track_order` → `submit_feedback`

**Degraded handoff:**
`handoffQuality: degraded` → complete `continue_url` → `update_order_status` with owning `agent_id` + `external_checkout_id` + `handoff_endpoint` → `track_order`

## Badges

| Badge | Action |
| --- | --- |
| `payable_now` | Autonomous `execute_order` OK (mandate active; confirm with user) |
| `needs_mandate` | `request_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 }`).

## Hints

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

## Correlation

Carry `search_id` from `search_supply` through details, execute, and feedback. Pass `idempotency_key` on every `execute_order`.