Servers Playground How we check Add a server Log in

Conduit Agentic Commerce

Working · 2.4 s

app.aiconduit/conduitv2.0.0 Domain verified

Search multi-merchant supply, checkout, and track orders via MCP.

Commerce

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.aiconduit.app/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

agent_authenticate

Two-step re-auth. Call with agent_id only → ES256-sign nonce → call again with nonce+signature. Prefer keys from ~/.conduit ({handle}.credentials.json or legacy credentials.json; CONDUIT_CREDENTIALS_PATH pins one file). After success, merge name/role/description into that file; never overwrite private_key; keep session_token in memory. Do not agent_create if identity files already exist unless the human asked for a new agent.

agent_idstring, required

Agent id from the chosen ~/.conduit credentials file, e.g. agt_...

noncestring

Challenge nonce from the first agent_authenticate call (omit to request one)

signaturestring

Signature of the nonce with the agent private key (omit with nonce to get challenge)

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Conduit Agentic Commerce MCP server | mcptry

Tools (25)

agent_authenticate

Argument	Type	Description
nonce	string	Challenge nonce from the first agent_authenticate call (omit to request one)
agent_id*	string	Agent id from the chosen ~/.conduit credentials file, e.g. agt_...
signature	string	Signature of the nonce with the agent private key (omit with nonce to get challenge)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id"
  ],
  "properties": {
    "nonce": {
      "type": "string",
      "description": "Challenge nonce from the first agent_authenticate call (omit to request one)"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id from the chosen ~/.conduit credentials file, e.g. agt_..."
    },
    "signature": {
      "type": "string",
      "description": "Signature of the nonce with the agent private key (omit with nonce to get challenge)"
    }
  }
}

agent_create

Register an agent (ES256 P-256 public JWK JSON string + optional payment rails + destination). BEFORE: list ~/.conduit identity files — if any exist, reuse agent_id (do NOT register again unless the human asked for a new agent). AFTER: write persist.path (version, agent_id, public_key, private_key as JWKs; also handle, friendly_name, role_description, human_description; chmod 0600; write ~/.conduit/active). Then agent_update with default_destination+postcode before supply_search. Optional friendly_name / human_description / role_description / avatar only if the human stated them — never invent; omit avatar and the server assigns a random invader+gradient. Omit handle to auto-generate (e.g. parcel-watcher-12).

Argument	Type	Description
avatar	any	Identity mark. Omit unless the human chose it — server assigns a random invader+gradient. { kind:"glyph", glyph:"invader"\|emoji, tint?:invader color, gradient } or { kind:"image", src }. Tint only for invader. Do not store in the credentials file.
handle	string	Optional display handle (lowercase kebab); omit to auto-generate e.g. parcel-watcher-12
public_key*	string	ES256 P-256 public JWK as a JSON string (kty=EC, crv=P-256, x, y). Not PEM, hex, or base64url-wrapped JSON. Keep the matching private JWK only in ~/.conduit/{handle}.credentials.json.
preferences	any	Optional agent preference bag
friendly_name	string	Human-facing label (≠ handle), e.g. EU Restock Bot
payment_rails

agent_notify

Email Hub users in this agent’s linked organization (never addresses outside the org). to=all or { user_id } / { role } / { email } matching agent_organization members. Optional actions (Hub URLs only), severity, idempotency_key. Channel is email.

Argument	Type	Description
to*	any	Who to notify: "all", { user_id }, { user_ids }, { role }, { roles }, or { email } matching an org member. Never an address outside the org.
body*	string	Plain-text body, max 4000 characters. Conduit wraps HTML; do not send markup.
title*	string	Subject line, max 120 characters
actions	array	Optional buttons, max 3. Hosts outside Conduit are rejected.
channel	string	Delivery channel. Email only — omit or pass email
dry_run	boolean	If true, resolve recipients and from-address without sending or storing
agent_id*	string	Linked agent sending the message
order_id	string	Optional order correlation

agent_organization

Read the linked organization (name, slug, country, default address) and members (user_id, name, role, email) for an agent. Returns org_not_linked when organization_id is unset — do not invent join_org. Use members to target agent_notify.

read-only

Argument	Type	Description
agent_id*	string	Agent id whose linked organization to read
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent id whose linked organization to read"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

agent_outreach

Email outside addresses (suppliers, carriers). to is a string email, { email }, or { emails } (max 5). Not to=all and not a Hub user_id / role — those are agent_notify. Linked agents set Reply-To to an org member (default OWNER). No action buttons. Channel is email.

Argument	Type	Description
to*	any	Outside address(es): a string email, { email }, or { emails } (max 5). Not to=all and not a Hub user_id / role — those are agent_notify.
body*	string	Plain-text body, max 4000 characters. URLs stay escaped text, not buttons.
title*	string	Subject line, max 120 characters
channel	string	Delivery channel. Email only — omit or pass email
dry_run	boolean	If true, resolve recipients and from-address without sending or storing
agent_id*	string	Authenticated agent sending the note
order_id	string	Optional order correlation
reply_to	any	Linked only: who receives replies. { email } or { role } matching a member. Omit to default to the OWNER. Unlinked agents have no Reply-To.

agent_report_issue

Report unexpected tool errors or confusing Conduit outcomes for AX review (agent_report_issue — not order_feedback). Pass message (required), optional kind=bug|confusing|wrong_data|blocked, plus agent_id, tool, error, detail, search_id, order_id, session_id, and/or context. Dedupes open reports with the same tool+error+correlation. Does not change reputation.

Argument	Type	Description
kind	string	Triage kind (default confusing): bug \| confusing \| wrong_data \| blocked
tool	string	MCP tool that failed or confused you, e.g. supply_search or order_execute
error	string	Error code from the prior tool response when present, e.g. offer_not_in_cache
detail	string	Optional longer detail (response excerpt, unexpected field). Do not include private_key.
context	object	Optional structured extras (args summary, badge, etc.). Secrets are stripped.
message*	string	Required: what went wrong or what confused you (expected vs actual). Keep actionable. This is agent_report_issue — not order_feedback.
agent_id	string	Agent id from credentials when available (omit placeholders like "agent_id")
order_id

agent_update

Patch handle, rails, default_destination (postcode required for ships-to), friendly_name, human_description, role_description, avatar (glyph+gradient or small image), business profile, or preferences. Set avatar only if the human chose it. Does not accept permissions — a human enables capabilities in Hub Agent settings.

Argument	Type	Description
avatar	any	Identity mark. Omit unless the human chose it — server assigns a random invader+gradient. { kind:"glyph", glyph:"invader"\|emoji, tint?:invader color, gradient } or { kind:"image", src }. Tint only for invader. Do not store in the credentials file.
handle	string	New display handle (lowercase kebab)
agent_id*	string	Agent id to patch, e.g. agt_...
preferences	any	Preferences patch
friendly_name	string	Human-facing label (≠ handle), e.g. EU Restock Bot
payment_rails	array	Replacement rail key list
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed
business_profile	any	Business profile patch

inventory_levels

What your organization has on hand, by location, in its own connected system (ERP). Pass skus or query. Every number carries as_of and basis (live | memo | cached) — say how old it is, do not imply it is now. Needs inventory permission. This is your OWN stock; a supplier's stock is supply_availability.

read-only

Argument	Type	Description
skus	array	Item codes in your own system, e.g. ["CART-6040"]. Pass skus or query
fresh	boolean	Ask the system now instead of reading the last value (slower, rate limited)
query	string	Free-text item search in your own system, e.g. "carton"
agent_id*	string	Agent id; its organization owns the connected system
connection_id	string	Which connected system, when the org has several
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id"
  ],
  "properties": {
    "skus": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Item codes in your own system, e.g. [\"CART-6040\"]. Pass skus or query"
    },
    "fresh": {
      "type": "boolean",
      "description": "Ask the system now instead of reading the last value (slower, rate limited)"
    },
    "query": {
      "type": "string",
      "description": "Free-text item search in your own system, e.g. \"carton\""
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id; its organization owns the connected system"
    },
    "connection_id": {
      "type": "string",
      "description": "Which connected system, when the org has several"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

inventory_purchase_order

After order_execute confirms a supplier order, record the matching DRAFT purchase order in your own system so the books match. Always a draft: a person confirms it there. Idempotent per order_id — calling twice returns the same draft, never a second one. Needs both inventory and checkout permission. Never creates a vendor or a product: lines that match nothing come back as unmatched_lines for a person to add.

Argument	Type	Description
agent_id*	string	Agent id; needs both inventory and checkout permission
order_id*	string	Conduit order id of a supplier order already placed with order_execute
connection_id	string	Which connected system, when the org has several
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id",
    "order_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent id; needs both inventory and checkout permission"
    },
    "order_id": {
      "type": "string",
      "description": "Conduit order id of a supplier order already placed with order_execute"
    },
    "connection_id": {
      "type": "string",
      "description": "Which connected system, when the org has several"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

inventory_replenishment

Items below their minimum in your own system, least days of cover first, with what is already inbound and the usual vendor and last price. Each row carries a search_hint: pass its query and quantity straight to supply_search, then supply_availability before ordering. Optional location scopes to one warehouse. Needs inventory permission.

read-only

Argument	Type	Description
fresh	boolean	Ask the system now instead of reading the last value
agent_id*	string	Agent id; its organization owns the connected system
location	string	Warehouse or store name to scope the worklist, e.g. "Jebel Ali". Omit for all
connection_id	string	Which connected system, when the org has several
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id"
  ],
  "properties": {
    "fresh": {
      "type": "boolean",
      "description": "Ask the system now instead of reading the last value"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id; its organization owns the connected system"
    },
    "location": {
      "type": "string",
      "description": "Warehouse or store name to scope the worklist, e.g. \"Jebel Ali\". Omit for all"
    },
    "connection_id": {
      "type": "string",
      "description": "Which connected system, when the org has several"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

inventory_suppliers

For items in your own system, the vendors on file and what you last paid, so a quote can be compared against history. Needs inventory permission. Does not contact any vendor.

read-only

Argument	Type	Description
skus*	array	Item codes in your own system whose usual vendors and last prices to read
agent_id*	string	Agent id; its organization owns the connected system
connection_id	string	Which connected system, when the org has several
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id",
    "skus"
  ],
  "properties": {
    "skus": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Item codes in your own system whose usual vendors and last prices to read"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id; its organization owns the connected system"
    },
    "connection_id": {
      "type": "string",
      "description": "Which connected system, when the org has several"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

order_dispute

Refund/chargeback/report paths for an order. Requires owning agent_id.

read-only

Argument	Type	Description
agent_id*	string	Owning agent id (required for authorization)
order_id*	string	Order id to resolve refund/chargeback/report paths for
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "order_id",
    "agent_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Owning agent id (required for authorization)"
    },
    "order_id": {
      "type": "string",
      "description": "Order id to resolve refund/chargeback/report paths for"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

order_events

Lifecycle timeline — transitions only. Pair with order_track. Requires owning agent_id.

read-only

Argument	Type	Description
agent_id*	string	Owning agent id (required for authorization)
order_id*	string	Order id whose lifecycle events to list
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "order_id",
    "agent_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Owning agent id (required for authorization)"
    },
    "order_id": {
      "type": "string",
      "description": "Order id whose lifecycle events to list"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

order_execute

Handoff or autonomous checkout. Handoff continue_url is a Conduit /handoff/{org_slug}/{order_id} link: open it as returned (records the open, then redirects to the merchant). Autonomous needs badge payable_now (covering mandate fits). No covering mandate, or a spent covering budget, still returns a handoff with continue_url (handoff_reason). Use idempotency_key. Prefer supply_delivery when only comparing delivery.

Argument	Type	Description
carrier	string	The shipping rate to buy, as the option's own `title` from supply_delivery. Conduit selects it on the merchant checkout, so the buyer opens the page on that rate instead of the merchant's default, which is the cheapest one. A title the merchant does not quote for this address leaves its default in place, and the response says so via shipping_selected.
agent_id*	string	Owning agent id
pay_with	string	Rail key to pay with when multiple are enabled
quantity	integer	Units to buy (default 1)
search_id	string	search_id from supply_search for correlation
supply_id*	string	Offer supply id to purchase
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

order_feedback

Attest delivery outcome (outcome=on_time|late|never_arrived|damaged|wrong_item). Requires owning agent_id. Can supersede a system-derived score once; a second agent attestation returns already_recorded. Poor outcomes next→order_dispute. Omit quality/carrier_rating if unknown.

Argument	Type	Description
notes	string	Free-text delivery/quality notes
outcome*	string	Observed fulfillment outcome. Sets status (on_time/late→DELIVERED, damaged/wrong_item→DISPUTED, never_arrived→FAILED) and reputation.
quality	number	Product quality 1-5 — omit if unknown (do not invent)
agent_id*	string	Owning agent id (required for authorization)
order_id*	string	Order id to attest
search_id	string	Optional search_id for analytics correlation
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed
carrier_rating	number	Carrier rating 1-5 — omit if unknown; used in reputation when provided

order_list

List orders for an agent ({ orders }). Optional status or open_only filter.

read-only

Argument	Type	Description
status	string	Optional status filter: PENDING, CONFIRMED, IN_TRANSIT, DELIVERED, ABANDONED (or CANCELLED), FAILED, DISPUTED
agent_id*	string	Owning agent id whose orders to list
open_only	boolean	If true, only in-flight orders (PENDING, CONFIRMED, IN_TRANSIT). Ignored when status is set.
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Optional status filter: PENDING, CONFIRMED, IN_TRANSIT, DELIVERED, ABANDONED (or CANCELLED), FAILED, DISPUTED"
    },
    "agent_id": {
      "type": "string",
      "description": "Owning agent id whose orders to list"
    },
    "open_only": {
      "type": "boolean",
      "description": "If true, only in-flight orders (PENDING, CONFIRMED, IN_TRANSIT). Ignored when status is set."
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

order_track

Honest deal-type-aware status (never fabricates carrier scans). Requires owning agent_id.

read-only

Argument	Type	Description
agent_id*	string	Owning agent id (required for authorization)
order_id*	string	Order id to track
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "order_id",
    "agent_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Owning agent id (required for authorization)"
    },
    "order_id": {
      "type": "string",
      "description": "Order id to track"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

order_update_status

Agent manual correction or degraded handoff recovery. note required except cancelled. Owning agent_id required.

Argument	Type	Description
note	string	Required note except when status=CANCELLED
status*	string	New status, e.g. PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
carrier	string	Carrier name when attaching tracking
agent_id*	string	Owning agent id (required for authorization)
order_id*	string	Order id to update
search_id	string	Optional search_id for analytics correlation
tracking_id	string	Carrier tracking id when recovering handoff
tracking_url	string	Carrier's public tracking page for tracking_id, when you have it. Never invent one.
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

payment_mandate

AP2 spend mandates. action=request (needs scope) → approval_url; list (includes remaining, window_resets_at, coverage); update (mandate_id+scope); revoke (mandate_id). update NEVER approves. Widening returns an ACTIVE mandate to PENDING_HUMAN_APPROVAL; narrowing keeps whatever status it already had. monthly_cap is a rolling 30-day window from create. Same category set as a live mandate replaces it at approval and keeps this period's spend. No covering mandate at checkout is handoff, not an error.

destructive

Argument	Type	Description
scope	object	Spend limits — required for action=request and action=update
action*	string	request = create mandate (needs scope); list = enumerate; update = change scope (needs mandate_id+scope); revoke = revoke (needs mandate_id)
expires	string	Optional ISO-8601 expiry, e.g. 2026-12-31T00:00:00Z
agent_id*	string	Owning agent id
mandate_id	string	Mandate id required for update/revoke
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

payment_methods

List or enable agent payment methods (action=list|enable) with friendly labels. Defaults: cod + x402. invoice (B2B) is coming_soon. bank_card is handoff-only.

Argument	Type	Description
rail	string	Rail key required when action=enable, e.g. x402 (not bank_card vault)
action*	string	list = enumerate rails; enable = turn on one rail
agent_id*	string	Agent id whose methods to list or enable
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id",
    "action"
  ],
  "properties": {
    "rail": {
      "type": "string",
      "description": "Rail key required when action=enable, e.g. x402 (not bank_card vault)"
    },
    "action": {
      "enum": [
        "list",
        "enable"
      ],
      "type": "string",
      "description": "list = enumerate rails; enable = turn on one rail"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id whose methods to list or enable"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

supply_availability

Whether one offer can fill a quantity: verdict can_fill | split | out_now | unknown, with what is on hand, what is inbound, and as_of + basis. Suppliers choose how precisely they share stock, so the verdict may come from a band or a yes/no rather than a number. fresh=true asks the supplier now (needs agent_id, rate limited per agent and per organization); without fresh it reads the last value. Call this before order_execute on any connector offer.

read-only

Argument	Type	Description
fresh	boolean	Ask the supplier now rather than reading the last value. Needs agent_id, and is rate limited per agent and per organization
quote	boolean	Also return the supplier's exact total with tax for this quantity, computed without saving anything. Needs agent_id and an account with the supplier
agent_id	string	Agent id. Required for fresh, and it is what reveals your negotiated prices
quantity	integer	Quantity to fill (default 1)
supply_id*	string	Offer supply id from supply_search / supply_details
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

supply_delivery

Non-committing checkout probe for shipping ETA/cost. Uses agent default_destination, else linked org default address, or country override. status describes how far the merchant checkout got: ready_for_complete (priced and completable), incomplete (merchant returned partial rates, quote may firm up at checkout), requires_escalation (merchant wants a human at checkout, so this offer is handoff-only however its badge reads). needs_interaction=true means the same. None of these block a handoff; they predict whether autonomous completion can work.

read-only

Argument	Type	Description
region	string	Optional region/state override
address	string	Street override. Many merchants will not quote shipping without it.
country	string	ISO country override, e.g. US (else agent/org destination)
agent_id	string	Agent id — uses agent destination else org default when country omitted
locality	string	City override. Needed with street for a real delivery quote.
quantity	integer	Units to price shipping for (default 1)
supply_id*	string	Offer supply id from supply_search / supply_details

supply_details

Re-reads one offer from the search cache and refreshes its badge/action against current mandate state. Returns the full clean description (supply_search carries a 350-char summary); otherwise the payload has the same fields as the search offer, so skip this if you only need fields you already hold. include_description_original=true adds description_original {format, content}, the merchant's own markup (untrusted), or description_original_omitted with the reason. Carries no shipping data: use supply_delivery for ETA and cost. Re-run supply_search if offer_not_in_cache.

read-only

Argument	Type	Description
agent_id	string	Agent id to refresh badge/action for mandate state
search_id	string	search_id from supply_search for correlation
supply_id*	string	Offer supply id from supply_search results
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed
include_description_original	boolean	Adds description_original {format, content}: the merchant's own markup, for rendering or checking our conversion. Untrusted merchant text. supply_details only.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "supply_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent id to refresh badge/action for mandate state"
    },
    "search_id": {
      "type": "string",
      "description": "search_id from supply_search for correlation"
    },
    "supply_id": {
      "type": "string",
      "description": "Offer supply id from supply_search results"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    },
    "include_description_original": {
      "type": "boolean",
      "description": "Adds description_original {format, content}: the merchant's own markup, for rendering or checking our conversion. Untrusted merchant text. supply_details only."
    }
  }
}

supply_options

Lists the selectable options (size, color, pack) for an offer whose has_options=true, with one variant per combination. Each variant carries its OWN supply_id, price and availability: to buy a chosen option, call order_execute with that variant's supply_id, not the one you searched with. Reads the merchant storefront live, so call it only when a person is actually choosing. Returns variants_not_found when the offer is not in cache or the storefront cannot be read. A single-variant product returns options:[] variants:[].

read-only

Argument	Type	Description
agent_id	string	Agent id, for permission and analytics
supply_id*	string	Offer supply id whose product options to list (has_options=true on the offer)
session_token	string	Session token from agent_authenticate — required whenever agent_id is passed

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "supply_id"
  ],
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent id, for permission and analytics"
    },
    "supply_id": {
      "type": "string",
      "description": "Offer supply id whose product options to list (has_options=true on the offer)"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

supply_search

Multi-provider discovery (live REAL merchants by default). Returns a ranked page (default limit=30, max 100) with total/has_more/next_offset. Follow next.args (search_id+offset+limit) to page without re-fanout. Optional fetch_limit (max 300) deepens the upstream pull on new searches. Pass include_sandbox=true only to append DEMO/SANDBOX test merchants at the bottom (test_offer=true). Always pass agent_id for mandate-aware badges. Carry search_id through supply_details / order_execute / order_feedback. Offer descriptions are clean text cut to 350 chars; supply_details returns the full text.

read-only

Argument	Type	Description
limit	integer	Page size of ranked offers to return (default 30, max 100)
query	string	Product search query, e.g. USB-C charger 65W. Required for a new search; omit when paging with search_id + offset
budget	any	Max total budget — number means USD; or { amount, currency }
offset	integer	0-based offset into the ranked set for this search_id (default 0). For page 2+, pass search_id from the prior response and follow next.args
country	string	ISO country for ships-to, e.g. US
agent_id	string	Agent id for mandate-aware badges (always pass when available)
quantity

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "public_key"
  ],
  "properties": {
    "avatar": {
      "description": "Identity mark. Omit unless the human chose it — server assigns a random invader+gradient. { kind:\"glyph\", glyph:\"invader\"|emoji, tint?:invader color, gradient } or { kind:\"image\", src }. Tint only for invader. Do not store in the credentials file."
    },
    "handle": {
      "type": "string",
      "description": "Optional display handle (lowercase kebab); omit to auto-generate e.g. parcel-watcher-12"
    },
    "public_key": {
      "type": "string",
      "description": "ES256 P-256 public JWK as a JSON string (kty=EC, crv=P-256, x, y). Not PEM, hex, or base64url-wrapped JSON. Keep the matching private JWK only in ~/.conduit/{handle}.credentials.json."
    },
    "preferences": {
      "description": "Optional agent preference bag"
    },
    "friendly_name": {
      "type": "string",
      "description": "Human-facing label (≠ handle), e.g. EU Restock Bot"
    },
    "payment_rails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional rail keys to seed, e.g. [\"x402\"]"
    },
    "business_profile": {
      "description": "Optional business profile metadata object"
    },
    "role_description": {
      "type": "string",
      "description": "Self-instruction for this agent only, e.g. manage EU supplies"
    },
    "human_description": {
      "type": "string",
      "description": "Description shown to humans on the org dashboard"
    },
    "default_destination": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "Alias of locality"
        },
        "name": {
          "type": "string",
          "description": "Recipient name; many merchants require it to fulfil"
        },
        "email": {
          "type": "string",
          "description": "Buyer contact email for the merchant order"
        },
        "phone": {
          "type": "string",
          "description": "Buyer phone in E.164, e.g. +12125550188"
        },
        "state": {
          "type": "string",
          "description": "Alias of region"
        },
        "region": {
          "type": "string",
          "description": "State / province"
        },
        "address": {
          "type": "string",
          "description": "Street address. Needed for checkout to prefill"
        },
        "country": {
          "type": "string",
          "description": "ISO country code, e.g. US"
        },
        "locality": {
          "type": "string",
          "description": "City. Needed for checkout to prefill"
        },
        "postcode": {
          "type": "string",
          "description": "Postal / ZIP code. Enough for search and delivery estimates"
        },
        "postal_code": {
          "type": "string",
          "description": "Alias of postcode"
        },
        "street_address": {
          "type": "string",
          "description": "Alias of address"
        }
      },
      "description": "Where orders ship. postcode + country is enough for supply_search and delivery estimates; add address, locality and region so checkout links arrive prefilled.",
      "additionalProperties": {}
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id",
    "to",
    "title",
    "body"
  ],
  "properties": {
    "to": {
      "anyOf": [
        {
          "type": "string",
          "const": "all",
          "description": "Every current member of the linked org"
        },
        {
          "type": "object",
          "required": [
            "user_id"
          ],
          "properties": {
            "user_id": {
              "type": "string",
              "description": "One org member user_id from agent_organization"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "user_ids"
          ],
          "properties": {
            "user_ids": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Org member user_ids from agent_organization"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "role"
          ],
          "properties": {
            "role": {
              "type": "string",
              "description": "Org role: OWNER, OPS, FINANCE, DEVELOPER, or VIEWER"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "roles"
          ],
          "properties": {
            "roles": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "One or more org roles"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "description": "Exact member email from agent_organization — not an arbitrary address"
            }
          }
        }
      ],
      "description": "Who to notify: \"all\", { user_id }, { user_ids }, { role }, { roles }, or { email } matching an org member. Never an address outside the org."
    },
    "body": {
      "type": "string",
      "description": "Plain-text body, max 4000 characters. Conduit wraps HTML; do not send markup."
    },
    "title": {
      "type": "string",
      "description": "Subject line, max 120 characters"
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "https URL on hub.aiconduit.app, aiconduit.app, or mcp.aiconduit.app, or a Hub path like /invoices"
          },
          "type": {
            "enum": [
              "primary",
              "danger",
              "ghost"
            ],
            "type": "string",
            "description": "Button style (default primary)"
          },
          "title": {
            "type": "string",
            "description": "Button label, e.g. View Invoices"
          }
        }
      },
      "description": "Optional buttons, max 3. Hosts outside Conduit are rejected."
    },
    "channel": {
      "type": "string",
      "description": "Delivery channel. Email only — omit or pass email"
    },
    "dry_run": {
      "type": "boolean",
      "description": "If true, resolve recipients and from-address without sending or storing"
    },
    "agent_id": {
      "type": "string",
      "description": "Linked agent sending the message"
    },
    "order_id": {
      "type": "string",
      "description": "Optional order correlation"
    },
    "severity": {
      "enum": [
        "info",
        "warning",
        "urgent"
      ],
      "type": "string",
      "description": "info (default), warning, or urgent — affects subject prefix and accent"
    },
    "search_id": {
      "type": "string",
      "description": "Optional search correlation"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Replay key — same agent + key returns the original notify_id without sending again"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id",
    "to",
    "title",
    "body"
  ],
  "properties": {
    "to": {
      "anyOf": [
        {
          "type": "string",
          "description": "One outside email, e.g. [email protected]"
        },
        {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "description": "One outside email"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "emails"
          ],
          "properties": {
            "emails": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Up to 5 outside emails"
            }
          }
        }
      ],
      "description": "Outside address(es): a string email, { email }, or { emails } (max 5). Not to=all and not a Hub user_id / role — those are agent_notify."
    },
    "body": {
      "type": "string",
      "description": "Plain-text body, max 4000 characters. URLs stay escaped text, not buttons."
    },
    "title": {
      "type": "string",
      "description": "Subject line, max 120 characters"
    },
    "channel": {
      "type": "string",
      "description": "Delivery channel. Email only — omit or pass email"
    },
    "dry_run": {
      "type": "boolean",
      "description": "If true, resolve recipients and from-address without sending or storing"
    },
    "agent_id": {
      "type": "string",
      "description": "Authenticated agent sending the note"
    },
    "order_id": {
      "type": "string",
      "description": "Optional order correlation"
    },
    "reply_to": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "description": "Org member email from agent_organization"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "role"
          ],
          "properties": {
            "role": {
              "type": "string",
              "description": "Org role, typically OWNER or OPS"
            }
          }
        }
      ],
      "description": "Linked only: who receives replies. { email } or { role } matching a member. Omit to default to the OWNER. Unlinked agents have no Reply-To."
    },
    "search_id": {
      "type": "string",
      "description": "Optional search correlation"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Replay key — same agent + key returns the original outreach_id without sending again"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "message"
  ],
  "properties": {
    "kind": {
      "enum": [
        "bug",
        "confusing",
        "wrong_data",
        "blocked"
      ],
      "type": "string",
      "description": "Triage kind (default confusing): bug | confusing | wrong_data | blocked"
    },
    "tool": {
      "type": "string",
      "description": "MCP tool that failed or confused you, e.g. supply_search or order_execute"
    },
    "error": {
      "type": "string",
      "description": "Error code from the prior tool response when present, e.g. offer_not_in_cache"
    },
    "detail": {
      "type": "string",
      "description": "Optional longer detail (response excerpt, unexpected field). Do not include private_key."
    },
    "context": {
      "type": "object",
      "description": "Optional structured extras (args summary, badge, etc.). Secrets are stripped.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "message": {
      "type": "string",
      "description": "Required: what went wrong or what confused you (expected vs actual). Keep actionable. This is agent_report_issue — not order_feedback."
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id from credentials when available (omit placeholders like \"agent_id\")"
    },
    "order_id": {
      "type": "string",
      "description": "order_id for correlation when the issue is order-related"
    },
    "search_id": {
      "type": "string",
      "description": "search_id for correlation when the issue is search-related"
    },
    "session_id": {
      "type": "string",
      "description": "Optional session id; Conduit also picks up x-conduit-session-id from the transport"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "agent_id"
  ],
  "properties": {
    "avatar": {
      "description": "Identity mark. Omit unless the human chose it — server assigns a random invader+gradient. { kind:\"glyph\", glyph:\"invader\"|emoji, tint?:invader color, gradient } or { kind:\"image\", src }. Tint only for invader. Do not store in the credentials file."
    },
    "handle": {
      "type": "string",
      "description": "New display handle (lowercase kebab)"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id to patch, e.g. agt_..."
    },
    "preferences": {
      "description": "Preferences patch"
    },
    "friendly_name": {
      "type": "string",
      "description": "Human-facing label (≠ handle), e.g. EU Restock Bot"
    },
    "payment_rails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Replacement rail key list"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    },
    "business_profile": {
      "description": "Business profile patch"
    },
    "role_description": {
      "type": "string",
      "description": "Self-instruction for this agent only, e.g. manage EU supplies"
    },
    "human_description": {
      "type": "string",
      "description": "Description shown to humans on the org dashboard"
    },
    "default_destination": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "Alias of locality"
        },
        "name": {
          "type": "string",
          "description": "Recipient name; many merchants require it to fulfil"
        },
        "email": {
          "type": "string",
          "description": "Buyer contact email for the merchant order"
        },
        "phone": {
          "type": "string",
          "description": "Buyer phone in E.164, e.g. +12125550188"
        },
        "state": {
          "type": "string",
          "description": "Alias of region"
        },
        "region": {
          "type": "string",
          "description": "State / province"
        },
        "address": {
          "type": "string",
          "description": "Street address. Needed for checkout to prefill"
        },
        "country": {
          "type": "string",
          "description": "ISO country code, e.g. US"
        },
        "locality": {
          "type": "string",
          "description": "City. Needed for checkout to prefill"
        },
        "postcode": {
          "type": "string",
          "description": "Postal / ZIP code. Enough for search and delivery estimates"
        },
        "postal_code": {
          "type": "string",
          "description": "Alias of postcode"
        },
        "street_address": {
          "type": "string",
          "description": "Alias of address"
        }
      },
      "description": "Where orders ship. postcode + country is enough for accurate search; add address, locality and region so checkout links arrive prefilled instead of blank.",
      "additionalProperties": {}
    }
  }
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "order_id",
    "agent_id",
    "outcome"
  ],
  "properties": {
    "notes": {
      "type": "string",
      "description": "Free-text delivery/quality notes"
    },
    "outcome": {
      "enum": [
        "on_time",
        "late",
        "never_arrived",
        "damaged",
        "wrong_item"
      ],
      "type": "string",
      "description": "Observed fulfillment outcome. Sets status (on_time/late→DELIVERED, damaged/wrong_item→DISPUTED, never_arrived→FAILED) and reputation."
    },
    "quality": {
      "type": "number",
      "maximum": 5,
      "minimum": 1,
      "description": "Product quality 1-5 — omit if unknown (do not invent)"
    },
    "agent_id": {
      "type": "string",
      "description": "Owning agent id (required for authorization)"
    },
    "order_id": {
      "type": "string",
      "description": "Order id to attest"
    },
    "search_id": {
      "type": "string",
      "description": "Optional search_id for analytics correlation"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    },
    "carrier_rating": {
      "type": "number",
      "maximum": 5,
      "minimum": 1,
      "description": "Carrier rating 1-5 — omit if unknown; used in reputation when provided"
    }
  }
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "action",
    "agent_id"
  ],
  "properties": {
    "scope": {
      "type": "object",
      "properties": {
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional category allowlist, Google Product Taxonomy level 1. Omit or pass [] for a General mandate (catch-all for unmatched and unclassified offers). Accepts the slug, the label, or the GPT numeric id. Slugs: electronics, office-supplies, business-and-industrial, hardware, furniture, home-and-garden, cameras-and-optics, software, media, apparel-and-accessories, luggage-and-bags, health-and-beauty, food-beverages-and-tobacco, sporting-goods, toys-and-games, baby-and-toddler, animals-and-pet-supplies, vehicles-and-parts, arts-and-entertainment, religious-and-ceremonial, mature. Most specific covering mandate wins; unknown category uses General; no covering mandate is handoff."
        },
        "monthly_cap": {
          "type": "number",
          "description": "Max spend in a rolling 30-day window from when the mandate was created, e.g. 500"
        },
        "max_per_order": {
          "type": "number",
          "description": "Max USD (or order currency) per single order, e.g. 50"
        }
      },
      "description": "Spend limits — required for action=request and action=update"
    },
    "action": {
      "enum": [
        "request",
        "list",
        "update",
        "revoke"
      ],
      "type": "string",
      "description": "request = create mandate (needs scope); list = enumerate; update = change scope (needs mandate_id+scope); revoke = revoke (needs mandate_id)"
    },
    "expires": {
      "type": "string",
      "description": "Optional ISO-8601 expiry, e.g. 2026-12-31T00:00:00Z"
    },
    "agent_id": {
      "type": "string",
      "description": "Owning agent id"
    },
    "mandate_id": {
      "type": "string",
      "description": "Mandate id required for update/revoke"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "supply_id"
  ],
  "properties": {
    "fresh": {
      "type": "boolean",
      "description": "Ask the supplier now rather than reading the last value. Needs agent_id, and is rate limited per agent and per organization"
    },
    "quote": {
      "type": "boolean",
      "description": "Also return the supplier's exact total with tax for this quantity, computed without saving anything. Needs agent_id and an account with the supplier"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id. Required for fresh, and it is what reveals your negotiated prices"
    },
    "quantity": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Quantity to fill (default 1)",
      "exclusiveMinimum": 0
    },
    "supply_id": {
      "type": "string",
      "description": "Offer supply id from supply_search / supply_details"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "description": "Page size of ranked offers to return (default 30, max 100)",
      "exclusiveMinimum": 0
    },
    "query": {
      "type": "string",
      "description": "Product search query, e.g. USB-C charger 65W. Required for a new search; omit when paging with search_id + offset"
    },
    "budget": {
      "anyOf": [
        {
          "type": "number",
          "description": "Legacy: max total budget in USD",
          "exclusiveMinimum": 0
        },
        {
          "type": "object",
          "required": [
            "amount",
            "currency"
          ],
          "properties": {
            "amount": {
              "type": "number",
              "description": "Max total in major units",
              "exclusiveMinimum": 0
            },
            "currency": {
              "type": "string",
              "minLength": 1,
              "description": "ISO currency for budget, e.g. USD"
            }
          },
          "description": "Max total budget in the given currency (indicative FX for other currencies)"
        }
      ],
      "description": "Max total budget — number means USD; or { amount, currency }"
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "0-based offset into the ranked set for this search_id (default 0). For page 2+, pass search_id from the prior response and follow next.args"
    },
    "country": {
      "type": "string",
      "description": "ISO country for ships-to, e.g. US"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent id for mandate-aware badges (always pass when available)"
    },
    "quantity": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Desired quantity (default 1)",
      "exclusiveMinimum": 0
    },
    "search_id": {
      "type": "string",
      "description": "Resume paging into a prior ranked set (with offset>0, or offset 0 without query). New searches with query mint a fresh search_id"
    },
    "fetch_limit": {
      "type": "integer",
      "maximum": 300,
      "description": "Optional override for per-merchant upstream pull (default max(20, limit*2), max 300). Ignored when paging via search_id+offset",
      "exclusiveMinimum": 0
    },
    "payable_with": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter to rails the agent can pay with, e.g. [\"x402\"]"
    },
    "session_token": {
      "type": "string",
      "description": "Session token from agent_authenticate — required whenever agent_id is passed"
    },
    "include_sandbox": {
      "type": "boolean",
      "description": "Include DEMO/SANDBOX merchants (listed last, test_offer=true). Default false — live REAL merchants only. Use only when testing Conduit checkout flows."
    }
  }
}