@buychat/mcp

A Model Context Protocol (MCP) server that lets AI agents — Claude Desktop, Cursor, terminal agents, and anything else that speaks MCP — discover and shop on the BuyChat marketplace.

It runs over the stdio transport and wraps the Ed25519-signed Neural Commerce Protocol (NCP v1) via @buychat/ncp-sdk. No new backend protocol — every call is a signed NCP request.

MCP host (Claude Desktop / Cursor)  ⇄  @buychat/mcp (stdio)  ⇄  NCP v1 (Ed25519)  ⇄  buychat.ng

Quick start

Add the server to your MCP host config.

Anonymous (discovery only)

{
  "mcpServers": {
    "buychat": {
      "command": "npx",
      "args": ["-y", "@buychat/mcp"]
    }
  }
}

With an agent identity (unlocks transactions)

{
  "mcpServers": {
    "buychat": {
      "command": "npx",
      "args": ["-y", "@buychat/mcp"],
      "env": {
        "BUYCHAT_AGENT_ID": "agt_your_marketplace_id",
        "BUYCHAT_AGENT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
      }
    }
  }
}

• Claude Desktop config lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
• Cursor: Settings → MCP → add the same buychat block.

Configuration (environment variables)

| Variable | Required | Default | Description | | --- | --- | --- | --- | | BUYCHAT_AGENT_ID | for signed tools | — | Your registered marketplace agent id. | | BUYCHAT_AGENT_PRIVATE_KEY | for signed tools | — | Ed25519 PKCS8 PEM private key. Inline \n escapes are accepted. | | BUYCHAT_AGENT_PRIVATE_KEY_FILE | optional | — | Path to a .pem file (alternative to the inline key). | | BUYCHAT_API_URL | optional | https://buychat.ng | NCP base URL. |

Register an agent and obtain a keypair from the BuyChat developer surface (/developers → "Register your agent"). The same key the SDK signs with works here.

Credential gating: with no credentials the server registers the read / discovery tools only. With both BUYCHAT_AGENT_ID and a private key it also registers the signed, transactional tools. (Set only one and it falls back to anonymous mode and warns on stderr.)

Tools

Read / discovery

| Tool | NCP mapping | Notes | | --- | --- | --- | | list_vendors | GET /ncp/v1/marketplace/agents | Public — works with no credentials. Lists marketplace agents/vendors with reputation badges. | | search_products | POST /ncp/v1/search (NcpClient.search) | Requires credentials (server signs the request). | | rank_products | POST /ncp/v1/rank (NcpClient.rank) | Re-rank candidate listing ids. Requires credentials. | | recommend | GET /ncp/v1/recommendations | Personalised for a principal the agent is authorized for. Requires credentials. | | get_listing | GET /ncp/v1/listings/:id | Full listing detail + trust + price intelligence. Requires credentials. |

Only list_vendors is genuinely anonymous; the other NCP read endpoints require a signed agent identity server-side. Called without credentials they return a clear "set your env vars" message instead of a raw 401.

Signed / transactional (require credentials)

| Tool | NCP mapping | Notes | | --- | --- | --- | | track_order | GET /ncp/v1/orders/:id | Read-only status + escrow. | | place_order | POST /ncp/v1/orders | Real purchase. Confirm-gated. | | open_negotiation | POST /ncp/v1/negotiate/open (NcpClient.openNegotiation) | Real binding offer. Confirm-gated. | | book_stay | POST /ncp/v1/stays/:id/book (preview via …/quote) | Real booking, holds funds. Confirm-gated. Requires FEATURE_STAYS_ENABLED on the server. | | book_ride | POST /ncp/v1/rides | Confirm-gated. Ride creation is a Phase-2 server capability and may return "not yet available". |

Never silent spend — the confirm gate

The four money-moving tools (place_order, open_negotiation, book_stay, book_ride) are confirm-gated:

1. First call (no confirm) → the tool does a read-only preview: it prices out the items / fetches a quote and returns a human-readable summary (item, vendor, price, fees, total, and exactly what will happen). Nothing is bought or booked.
2. The MCP host shows that summary to the human.
3. Second call ("confirm": true) → only now does the tool perform the real action.

Combined with the MCP host's own per-tool-call approval prompt, this guarantees an agent can never silently move a human's money.

Development

pnpm install                       # from the monorepo root
pnpm --filter @buychat/mcp build   # tsc → dist/

# Smoke test (lists tools, then exits):
node packages/mcp-server/dist/index.js   # speaks MCP over stdio; Ctrl-C to stop

The server writes the protocol to stdout; all logs go to stderr.

License

MIT © BuyChat