# Seedhape user and agent guide

Use Seedhape to find paid services, check their prices, and let an agent pay
within the spending limit the user set. When the user wants to buy something,
go straight to discovery (`discover_offers` or `search_services`), `quote` the
exact URL, show the user the price, then call `pay` with the URL. Seedhape
checks the limit and asks the user itself when a purchase needs their OK.

If the account is not set up yet (a tool returns `SETUP_INCOMPLETE`, or
`user_readiness` is not ready), send the user to the setup link instead of
walking them through tools one by one. See "Finish setup" below.

## Connect this agent to Seedhape MCP

The hosted remote Streamable HTTP MCP endpoint is:

```text
https://www.seedhape.com/mcp
```

Choose the instructions for your client. Add this server once; after that,
select/enable Seedhape in the chat or agent and ask it to call `spending_status`
to confirm the tools work.
When OAuth opens a browser, sign in to the Seedhape account you want the agent
to use and approve the connection. Authentication connects the account; it
does not authorize spending.

### Codex

In a terminal where Codex is installed, add the server and then follow the
login hint Codex prints. For example:

```bash
codex mcp add Seedhape --url https://www.seedhape.com/mcp
```

When Codex reports `Added global MCP server 'Seedhape'. MCP server may or may
not require login. Run codex mcp login Seedhape to login.`, run:

```bash
codex mcp login Seedhape
codex mcp list
```

Complete browser sign-in if prompted. If login reports that authentication is
not required, use `codex mcp list` to confirm the server status anyway. Then
start or reload the Codex chat and ask it to call `spending_status`; that verifies
the tools are actually available to the agent, not merely present in config.
Codex CLI and its IDE extension share the MCP configuration. The equivalent
remote server entry in `~/.codex/config.toml` is:

```toml
[mcp_servers.Seedhape]
url = "https://www.seedhape.com/mcp"
```

### ChatGPT

In ChatGPT on the web, open **Settings → Apps** (workspace administrators may
need to enable Developer mode/custom connectors first), choose **Create app**
or **Add custom connector**, enter `https://www.seedhape.com/mcp`, and complete
the authentication/tool-scan flow. Enable the Seedhape app for the chat and
select it from the tools/apps menu. Custom MCP connector controls and write
tools vary by plan and workspace policy; if those controls are absent, the
account administrator or plan may not support custom MCP apps.

### Claude

**Claude Code:** in a terminal, run:

```bash
claude mcp add --transport http seedhape https://www.seedhape.com/mcp
claude mcp list
```

Then run `/mcp` inside Claude Code and authenticate if prompted. For Claude
web/Desktop, open **Settings → Connectors → Add custom connector**, enter
`https://www.seedhape.com/mcp`, add it, then click **Connect** and enable the
connector in the chat's tools menu. Team/Enterprise workspaces may require an
owner to allow or add the connector first.

### Google Antigravity

In Antigravity, open **Settings → Customizations → Installed MCP Servers** and
add a remote MCP server, or use **Manage MCP Servers → View raw config**. Add
this entry to the `mcpServers` object in
`~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json`
(workspace):

```json
{
  "mcpServers": {
    "seedhape": {
      "serverUrl": "https://www.seedhape.com/mcp"
    }
  }
}
```

Save/reload the server, select **Authenticate** if shown, finish Seedhape
sign-in in the browser, then confirm the server is connected and enable its
tools.

### If browser OAuth is unavailable

For clients that require a bearer token, sign in at
`https://seedhape.com/connect`, create a token, and copy it immediately
(it is shown once). Configure the server with the HTTP header
`Authorization: Bearer <token>` using that client's secure secrets/settings
store. Do not commit a real token in a project config or paste it into a chat.
If the client supports Seedhape's OAuth flow, prefer that over a static token.

### Verify the connection

In the client, inspect the connected server/tool list and call
`spending_status`, a read-only check. If the Seedhape tools are not present,
report that the MCP server is not connected or authenticated and give the
relevant setup steps; do not claim to have connected just because this file
was pasted. Once tools are available, call `user_readiness` for a quick
can-it-pay check; if setup is incomplete, give the user the setup link
(see "Finish setup").

Never paste private keys, seed phrases, wallet passwords, card details, Stripe
secrets, or one-time payment credentials into an agent conversation. The MCP
token authenticates the account; it does **not** authorize spending.

Generic HTTP MCP configuration (for clients that use this format):

```json
{
  "mcpServers": {
    "seedhape": {
      "url": "https://www.seedhape.com/mcp",
      "headers": { "Authorization": "Bearer <paste-token-here>" }
    }
  }
}
```

Use the client-specific setup above where its configuration format differs.

## Finish setup

Setup is one page for the user, not a series of agent steps. Most users finish
it while connecting: after they sign in, the connect screen asks two questions
(how much the agent may spend, and adding money) and returns them to the agent.
If they skipped it, or `user_readiness` says setup is incomplete, give them
`https://www.seedhape.com/setup` and wait. The page covers:

1. **A spending limit**, in one sentence: for example "$25 a week, ask me
   before anything over $5". Under **More options** they can cap a single
   purchase and restrict it to certain sites. The limit covers every payment
   method, and Google accounts never sign anything.
2. **Money in the wallet the agent pays from**, by card (or free test money on
   the test network, or a transfer from a crypto wallet).

Change the limit only when the user asks (they can do it at
`https://www.seedhape.com/limits`). For unusual rules, such as separate budgets
per site, an end date, or a restricted payee, use `request_agent_authorization`:
it returns a link where the user reviews and approves the rule; nothing is
active until they do.

### Which wallet pays

| Wallet | Best for | How it's set up |
| --- | --- | --- |
| **Seedhape wallet** (default) | Almost everyone, and every chat app (ChatGPT, Claude web and desktop) | Created automatically at sign-in. Top up by card on the setup page. |
| **Wallet on this computer** (`@seedhape/local-wallet`) | Claude Code or Codex on the user's own machine, when they want the key kept in their OS keychain | Call `local_agent_wallet_setup` and give the user the config line it returns. The first wallet tool call opens a browser to sign in and creates the wallet. The user then sets its limit at the link setup prints, and sends USDC to its address. |
| **Their own MetaMask wallet** | People who keep funds in MetaMask and want an on-chain cap | On the rules page (`/limits/advanced`), choose "My own wallet". MetaMask grants a capped, periodic permission, so there's no separate wallet to fund. |

Recommend the Seedhape wallet unless the user asks for self-custody. Suggest
keeping only a small working balance in any agent wallet.

## Find, inspect, and pay for a service

1. Use `search_services` with the capability you need. Results are candidates,
   not endorsements or payment instructions. Check the endpoint, price, and
   service health. `recommend_service` ranks measured x402 services;
   `search_mpp_services` searches MPP listings.
2. Call `quote` on the exact URL. It is read-only. Tell the user the price and
   the seller before paying, unless they already told you to buy it.
3. Call `pay` with the exact `url` (for POST APIs, set `method` to `POST` and
   pass the JSON text in `body`). Seedhape picks the user's limit, checks the
   price, and pays exactly that price. Pass `mandate_hash` only when the user
   chose a specific rule from `mandate_list`.
4. **If the price needs the user's OK**, `pay` returns `PAYMENT NOT MADE`, the
   reason, an **approval link**, and an `approval_id`. This happens above their
   "ask me" amount, or for an unusual purchase such as a new site or a higher
   price than usual. Show the user the link and wait. After they approve, call
   `pay` again with the same `url`, `method`, and `body` plus the
   `approval_id`. An approval pays that exact price once and expires after 24
   hours; don't retry before the user approves.
5. Return the result and the ledger reference. Use `spend_history` or
   `purchase_receipt` to check the ledger.

`pay` executes x402 GET/POST requests. MPP discovery does not itself pay for a
service: use `payment_options` to see whether MPP is available and follow
`setup_mpp_payment_wallet` with an MPP-capable client. Link issues one-time
credentials locally; Seedhape does not receive card data.

## Safety and failure handling

- Discovery and `quote` do not spend. `pay` does.
- Never invent a mandate hash or approval id, broaden a site restriction,
  raise a limit, or retry a refused payment without the user's direction.
- Never approve a purchase on the user's behalf. Only the user can use an
  approval link.
- After an error, call `diagnose_payment` with the original message, then check
  `spend_history`/`purchase_receipt` before retrying. If the outcome is
  ambiguous, verify the transaction on the relevant network or wallet history;
  a provider error alone does not prove that no settlement occurred.
- A payment to one provider's hostname cannot be redirected to another
  provider under a site-restricted limit or rule. Ask the user to change it
  first.
- To stop future agent spending, use `pause_spending` only when the user asks.
  To disconnect agent access, use `disconnect_agents`. Pausing or disconnecting
  does not reverse a settled payment.

## Optional protocols and recovery

`setup_status` and `payment_options` are the source of truth for enabled
capabilities. MPP, ACP, UCP, WebMCP, and Web Bot Auth may be preview or
merchant-specific; do not infer they are ready just because a listing exists.
AP2 evidence is optional for external x402 merchants; the buyer-side Seedhape
mandate and spending policy still apply.

## How Seedhape works

Seedhape is the buyer's spending-control and payment layer, not a guarantee
that every listed provider is reliable. The user's limit (an amount per day,
week, or month, an "ask me above" amount, and optional per-purchase and site
restrictions) and the pause switch apply to every purchase. Underneath, the
limit is a signed mandate; extra rules made on the advanced rules page are
mandates too. The wallet the agent pays from must also hold enough money. A
connection token only identifies the account; it cannot spend.

For x402, the agent reads a quote and makes a paid request. Seedhape checks
the limit and pause switch, asks the user when the price needs their OK,
reserves the amount, and builds the payment for exactly the quoted price. The
seller's facilitator verifies and settles it before the seller fulfills the
request, and Seedhape records the result. A provider error by itself is not
proof that settlement did not happen.

MPP is a separate payment path using the buyer's Link wallet and an MPP-capable
client; the hosted `pay` tool is x402-only.

## Hosted MCP tool reference

The following tools are exposed by `https://www.seedhape.com/mcp`. Arguments
are tool input fields (omit optional fields unless needed). Read-only tools
are marked “read”; controls and payment tools can change state or spend.
The client's tool schema is authoritative if an argument or capability has
changed.

### Discover services and prepare purchases

| Tool | Inputs | Use |
| --- | --- | --- |
| `search_services` | `query`; optional `category`, `status` (`unknown`, `live`, `degraded`, `down`, `dead`), `limit` (1–100, default 20) | Search service listings across supported catalogs. Results are candidates, not verified recommendations. |
| `search_mpp_services` | Optional `query`, `category`, `status`, `limit` (1–100, default 20) | Search MPP listings; discovery does not create credentials or make a payment. |
| `recommend_service` | `capability`; optional `prefer` (`balanced`, `reliable`, `fastest`, `cheapest`), `max_price`, `n` (1–10, default 3) | Rank services against a capability and preference. Verify the returned endpoint and terms yourself. |
| `get_service_health` | `service_id` (UUID) | Read the latest health information for a listed service. |
| `discover_offers` | Optional `query` | Search offers in the authenticated user's Seedhape-hosted merchant catalog. |
| `commerce_catalog` | None | Read the available Seedhape commerce catalog. It is not merchant account administration. |
| `commerce_prepare_purchase` | `product_id` | Prepare a purchase by returning the product's hosted endpoint or checkout link; does not pay. |
| `quote` | `url`; optional `method`, `body` | Read the price for the exact URL: plain-words `offers`, raw `accepts` terms, and a `quoteFingerprint`. Does not spend. |

### Account, wallet, and payment readiness

| Tool | Inputs | Use |
| --- | --- | --- |
| `setup_status` | None | Detailed setup checklist. Prefer sending the user to `https://www.seedhape.com/setup`; use this when you need to explain exactly what is missing. |
| `user_readiness` | None | Read account readiness and `nextAction`; does not change setup. |
| `wallet_status` | None | Read wallet/network, mandates, allowance/grant and FX setup information. |
| `payment_options` | None | Read available rails and prerequisites. MPP availability depends on account configuration and an MPP mandate. |
| `wallet_balance` | Optional `agent_id` | Read agent-wallet balance; omit ID for the default wallet. |
| `spending_status` | None | Read paused state, budget use, reservations and remaining allowance. |
| `merchant_payment_status` | None | Seller side: whether this account has a payout balance and connected Stripe. Not a buyer wallet check. |
| `publish_product` | HTTPS `upstream_url`, `price`; optional `name`, `description` | Seller side: list an API for sale, only when the user asks. See the merchant guide at `/merchant/SKILL.md`. |
| `managed_agent_wallet` | Optional `action` (`status` or `provision`; default `status`) | Check or provision a managed agent wallet. Provisioning alone does not grant spend authority. |
| `local_agent_wallet_setup` | None | Get the MCP config line for the local wallet (`npx -y @seedhape/local-wallet`). Its first tool call opens a browser to sign in and creates the wallet in the OS keychain; only the public address is registered. |
| `setup_mpp_payment_wallet` | None | Get Link CLI setup instructions. It does not issue or return a payment credential. |

### Register or manage agent identity

| Tool | Inputs | Use |
| --- | --- | --- |
| `external_agent_wallet_challenge` | `agent_id`, EVM `address`; optional `chain` | Create a short-lived ownership challenge for an external wallet. |
| `register_external_agent_wallet` | `agent_id`, `address`, exact `message`, `signature`; optional `chain`, `public_key` | Verify the signed challenge and register public wallet metadata. Sign locally; never send a private key. |
| `external_agent_wallet_status` | Optional `include_revoked` (default false) | List registered external agent wallets and their status. |
| `revoke_external_agent_wallet` | `agent_id` | Revoke that external wallet registration. |
| `web_bot_auth_key_setup` | `agent_id`; optional HTTPS `signature_agent` | Get the one command (`seedhape webbotauth:init`) that creates, registers, and uses the agent's Ed25519 identity key. It is also part of `seedhape setup`. |
| `web_bot_auth_challenge` | `agent_id`, `signature_agent`, `key_id` | Request a short-lived registration/rotation challenge. |
| `register_web_bot_auth_key` | `agent_id`, `signature_agent`, `key_id`, public Ed25519 JWK, `challenge`, `signature` | Register a public key after signing the exact challenge locally. |
| `rotate_web_bot_auth_key` | Same fields as registration | Register a replacement key; switch clients, then revoke the old key. |
| `revoke_web_bot_auth_key` | `signature_agent`, `key_id` | Revoke a registered Web Bot Auth key. |
| `create_acp_token` | Optional `label` (1–128 chars), `valid_for_days` (1–90, default 30) | Create an ACP integration token, shown once. It is not a payment mandate. |
| `create_yara_readonly_token` | None | Create a token for Yara to view spending only. It cannot quote or pay. |
| `create_yara_purchase_token` | None | Create a token for Yara to buy only quotes the user approves in Yara, within their limit. |
| `agent_identity_status` | None | Optional: whether this agent has an on-chain identity, for sellers that ask for one. Never required to buy. |
| `agent_verify_interaction` | Signed interaction receipt | Check a seller's signed response against the on-chain record. Read-only. |
| `agent_review`, `agent_review_update` | Signed interaction receipt, rating 1–5 | Leave or change a review only when the user asks. |
| `agent_reputation` | Agent identity | Read an agent's verified on-chain reviews. Read-only. |

### Mandates, funding, and spending controls

| Tool | Inputs | Use |
| --- | --- | --- |
| `request_agent_authorization` | `purpose` (at least 8 chars), `max_per_transaction`, `max_per_period`, `period` (`hour`, `day`, `week`, `month`); optional `max_transactions` (default 20), `valid_for_days` (default 1), `payment_rail` (`x402`, `mpp`, `both`), `allowed_hosts`, `allowed_pay_to` | For special rules beyond the user's limit (per-site budgets, end dates, restricted payees). Returns a link; nothing is active until the user approves it. |
| `mandate_list` | None | Read signed active mandates and their hashes, scope, limits, rail, network and expiry. Copy the exact hash; never guess one. |
| `mandate_revoke` | `mandate_hash` | Revoke a mandate in Seedhape. This does not necessarily revoke a separate on-chain token allowance. |
| `fund_agent_wallet` | None | Get the legacy/default agent-wallet funding instructions. |
| `fund_managed_agent_wallet` | None | Get funding instructions for the managed wallet. |
| `fund_external_agent_wallet` | `agent_id` | Get funding instructions for the selected external wallet. |
| `withdraw_agent_funds` | `amount` (decimal string), EVM `destination`; optional `agent_id` | Prepare a user-controlled withdrawal. This tool does not sign or submit the transfer. |
| `set_spending_budget` | optional `amount`, `period` (what the user asked for) | Changes nothing. Returns the current limit and the `/limits` link where the user changes it themselves. Agents can't raise or lower the limit. |
| `pause_spending` | `paused` (boolean) | Pause or resume future spending only when requested. Completed payments are not reversed. |
| `disconnect_agents` | None | Revoke all active MCP connections for the authenticated account. This is broad and disconnects every agent. |

### Execute payments and inspect results

| Tool | Inputs | Use |
| --- | --- | --- |
| `pay` | `url`; optional `method` (`GET` or `POST`), string `body`, `approval_id`, `mandate_hash`, `purchase_id`, `confirm_unusual` | Buy from an x402 URL at exactly the checked price. If the user must approve first, nothing is paid and the reply has an approval link and `approval_id`; call again with it after they approve. Use `confirm_unusual` only after the user reviewed a flagged purchase in this conversation. |
| `diagnose_payment` | Original `error` text (up to 2,000 chars); optional `failed_tool` | Turn an error into its code, the exact next tool, and a plain-language hint. Only needed when an error does not already include a next step. It does not retry or spend. |
| `spend_history` | None | Read recent payment attempts, including settled, failed and blocked entries. |
| `spending_statement` | Optional `since_days` (1–3,650, default 365) | Read a spending statement for the selected lookback. |
| `purchase_receipt` | `purchase_id` (Seedhape ledger ID) | Read the receipt for a purchase belonging to the authenticated account. |

Suggested sequences:

- New user: `user_readiness` → if not ready, give them `https://www.seedhape.com/setup` and wait → `user_readiness` again.
- Find and pay: `search_services` → `quote` → tell the user the price → `pay` with the URL → if it returns an approval link, show it, wait, then `pay` again with `approval_id` → `purchase_receipt`.
- Wallet on this computer: `local_agent_wallet_setup` → user adds the config line → first local wallet tool call opens sign-in → user sets its limit and adds USDC.
- MPP: `search_mpp_services` → `payment_options` → `setup_mpp_payment_wallet` with an MPP-capable client. Do not call hosted `pay` expecting it to run an MPP payment.

## What this MCP does not do

The hosted MCP exposes 51 tools, but not all Seedhape product features are MCP
tools. It does not provide a generic MPP `pay` operation, a merchant dashboard,
or arbitrary merchant administration. Use the web dashboard and the relevant
merchant/API integration for those. Tool availability and feature readiness
can differ by account; inspect `setup_status`, `payment_options`, and the tool
schemas at connection time.

Every Seedhape error names its own fix. JSON errors include `error.code`,
`error.recovery.tool` (with `arguments` when needed), `error.recovery.requiresUserConfirmation`,
and `error.hint` in plain language. A refused `pay` ends with `Error code:` and
`Next step:` lines. Follow the named tool instead of retrying, and ask the user
first whenever `requiresUserConfirmation` is true.

| Problem | Safe next step |
| --- | --- |
| Needs the user's approval | Show the approval link from `pay`; after they approve, call `pay` again with the `approval_id`. |
| No spending limit covers the site | Give the user `https://www.seedhape.com/setup` (or `/limits`); wait for them. |
| Site, amount, or period outside the limit | Stop; ask whether the user wants to change their limit. |
| Limit used up for this period | Inspect `spending_status`; the user can raise it at `/limits` if they want. |
| Spending paused | Stop; resume only if the user asks. |
| Wallet unfunded | Check `wallet_balance`, then send the user to `/setup` to add money (or the matching funding tool). |
| Stale challenge | Get a fresh quote before considering another payment attempt. |
| Provider or settlement error | Inspect the ledger and transaction evidence before retrying. |
| Local wallet unavailable | Use `local_agent_wallet_setup`; its first tool call finishes setup in the browser. Private keys stay local. |