# Swop MCP

Sell to people and AI agents, paid in USDC, from any MCP client.

**Connect:** `https://mcp.swopme.co/mcp/commerce` (Streamable HTTP)
Public tools need no account; account tools use OAuth 2.1 (dynamic client registration, PKCE).
Registry: `io.github.Travisswop/swop`

- Create products and get one link: people see a Buy page, agents get an x402 USDC challenge
- Feature products on your Swop SmartSite
- Checkout on your own site with signed webhooks (`checkout.paid`, `payout.released`)
- Browse and buy from any swop.id's store
- Orders, SmartSite editing, swop.id lookup

Sellers are agent-payable in USDC as soon as they add a product, with no
verification step.

Setup for Claude, ChatGPT, Cursor and Grok: [docs/add-swop-to-your-ai.md](docs/add-swop-to-your-ai.md)

```
claude mcp add --transport http swop https://mcp.swopme.co/mcp/commerce
```

## Tools (`/mcp/commerce`)

Public, no account:
- `swop_search_identities`, `swop_lookup_identity`: swop.id → profile + wallet addresses
- `swop_get_store`: any seller's products with USDC prices and an x402 buy URL for each
- `swop_get_product_link`: the one link that sells a product to people and agents

Sell (scope `commerce.write`):
- `swop_create_product`, `swop_update_product`, `swop_list_my_products`, `swop_feature_product`

Checkout on your own site (scope `commerce.write`):
- `swop_create_checkout`, `swop_get_checkout`
- `swop_register_webhook`, `swop_list_webhooks`, `swop_test_webhook`, `swop_remove_webhook`
  (HMAC-signed `checkout.paid` / `payout.released`)
- `swop_register_embed_origin`, `swop_list_embed_origins`, `swop_remove_embed_origin`

SmartSite storefront (scope `smartsite.write`):
- `swop_get_my_smartsite`, `swop_update_my_smartsite`, `swop_add_link`, `swop_remove_link`
- `swop_create_feed_post`: public post as the linked SmartSite, caption + up to 4 images.
  Two-step: preview returns a sealed `previewId`; confirm resends the identical content,
  and each preview publishes at most once. The backend hosts the images; this server
  uploads nothing.

Account (scopes `profile.read`, `wallet.read`):
- `swop_get_my_profile`, `swop_get_my_orders`, `swop_get_my_balances`,
  `swop_list_my_tokens` (store-credit "Bucks")

The commerce endpoint has no tools that send funds. Its OAuth metadata
(`/.well-known/oauth-protected-resource/mcp/commerce`) advertises only
`profile.read wallet.read smartsite.write commerce.write`.

## Full endpoint (`/mcp`)

`https://mcp.swopme.co/mcp` stays live for existing Swop users. It is the
commerce set plus wallet and market tools (sends, x402 payments, swaps,
perps and prediction-market data); the money-moving ones need the owner to
turn on AI spending, with caps, in the Swop app. New setups should use `/mcp/commerce`.
The same OAuth link works on both endpoints.

## Run

```
npm install
npm run dev          # Streamable HTTP on :8788 (POST /mcp and /mcp/commerce), stateless JSON mode
npm run dev:stdio    # stdio transport for local clients
npm run build && npm start
npm run smoke        # endpoint smoke test (in-process); `npm run smoke -- https://mcp.swopme.co` for prod
```

Env: `SWOP_API_BASE` (default https://apps.apiswop.co), `PREDICTIONS_API_BASE`
(default https://polymarket.apiswop.co), `PUBLIC_BASE_URL` (default
https://mcp.swopme.co), `PORT` (default 8788).

Local test with Claude Code:

```
claude mcp add swop --transport http http://localhost:8788/mcp/commerce
```

## Deploy

Stateless Vercel function (project `swop-mcp`), served at `mcp.swopme.co`
(never swop.tech). Deployed only with `vercel deploy --prod`; a git push does
not ship it. Registry entry: `server.json`, published with `mcp-publisher publish`.

## Where this fits

The AI-assistant edge of the platform. Exposes Swop to anything that speaks MCP,
reaching the same API every first-party client uses.

```mermaid
graph LR
    ai["Claude / ChatGPT / Cursor"] --> mcp["<b>swop-mcp</b>"]
    mcp --> api["swop-app-backend<br/>apps.apiswop.co"]
```

The identity rule that matters here: **crypto payment is never KYC-gated.** An
agent can pay a seller in USDC with no verification step. Verification gates the
card scope only — never ask a crypto path for identity.

For the cross-repo map, see **[swop-app-backend/docs/ECOSYSTEM.md](https://github.com/Travisswop/swop-app-backend/blob/main/docs/ECOSYSTEM.md)**.

## License

MIT — see [LICENSE](LICENSE).

## Ask Swop read connectors

The full `/mcp` endpoint now exposes `swop_get_token_price`, `swop_get_sports`,
and `swop_get_help`, using the same verified adapters as Ask Swop in the app and
Messages. All three require the linked account's `profile.read` scope and cannot
transfer funds. `swop_get_help` is also available on `/mcp/commerce`; prices and
sports remain on the full endpoint. Exact token contracts and network names are
preserved. Provider failures and ambiguous assets return an explanation rather
than an invented price, score or market.

Run `npm run build && node scripts/test-assistant-connectors.mjs` for protocol,
authentication, input-validation and endpoint-isolation checks.