{"id":"remote-mcp","title":"Hosted MCP connection for agents","markdown":"# Hosted MCP for agents\n\nClient-specific setup: [Claude, Qwen Code, Gemini CLI and Cursor](https://agent-utilities.agent-utilities.workers.dev/integrations/agents). Agents can read credential-free configuration templates and a free first task at [the client entry-point API](https://agent-utilities.agent-utilities.workers.dev/v1/content/clients). These are documented configurations, not claims of vendor-app installation or automatic access for every model.\n\nConnect a Streamable HTTP MCP client to:\n\nhttps://agent-utilities.agent-utilities.workers.dev/mcp/remote\n\nFor shopping tools only, use:\n\nhttps://agent-utilities.agent-utilities.workers.dev/mcp/remote?category=commerce\n\nNo local adapter or Node installation is required by the service. Your client must support Streamable HTTP. Free discovery and preparation work without a key. Paid calls require a client that can send a private `Authorization: Bearer <API key>` HTTP header. This endpoint does not implement OAuth; clients that require OAuth cannot use it for paid execution. Never put credentials in a URL, prompt or tool arguments. The API key and $1 or $5 Stripe credit packs are the same as the other credit clients. This connection cannot purchase or top up credits and cannot sign USDC payments.\n\n## Discover before funding\n\nConnect, then use `tools/list` and `resources/list`. Resources include service documentation and fixed input/output examples. `resources/read` is free and does not execute custom inputs. You may also read `/v1/content/index` directly without MCP.\n\nThe full catalog has 36 paid tools and five free helpers (small custom pack previews, supplied-HTML offer previews, fixed examples, preparation and authenticated balance). The commerce scope has seven paid tools and all five helpers; other category scopes omit both custom previews. Category filtering affects discovery, not the permissions of your API key. Available categories: html, web, contracts, security, agents, data, text, commerce.\n\n## Extract offers from your own small HTML sample free\n\nCall `agent_utilities_offer_preview` with `html`, optional `baseUrl`, and optional `maxOffers` (1–3, default 3). It uses the same Product/Offer JSON-LD extractor as `commerce.offer-extract`. The serialized arguments must fit 16384 UTF-8 bytes. No credentials, payment or page fetch are used. Only send HTML you are authorized to process; do not include session tokens or unrelated private content.\n\nFor ordinary HTTP, POST the same JSON to `https://agent-utilities.agent-utilities.workers.dev/v1/preview/commerce.offer-extract` with `Content-Type: application/json`; the complete body including whitespace must fit 16384 bytes. Input/output schemas and a runnable example are in `/v1/content/index` under `freePreviews` and in `/openapi.json`.\n\nInspect `result.truncated`, source pointers, warnings and missing fields. More than three extracted offers returns a truncated result, not a claim to cover the page. No JSON-LD offers can legitimately produce an empty list. Declared offers are not verified live prices or inventory, and scripts are not executed. The envelope reports `executionPerformed: true` and `chargedMicroUsd: \"0\"`. Oversized inputs are rejected with no paid fallback. Larger documents require a separately authorized $0.0008 `commerce.offer-extract` call; this preview never purchases it.\n\n## Try your own small pack plan free\n\nCall `agent_utilities_pack_preview` with the pack input directly: `currency`, `minorUnitDigits`, `requiredUnits`, and `offers` containing `id`, `unitsPerPack`, `price`, and `maxPacks`. It computes your supplied input without a key, credit balance or payment. Limits: three offers, 1000 required units, 1000 units per pack, 50 packs per offer, and 4096 input bytes. It uses the same exact item-subtotal calculation as the full planner; shipping, tax and fees remain excluded. Product equivalence and stock are caller assertions.\n\nThe result has `mode: \"free-preview\"`, `executionPerformed: true`, `chargedMicroUsd: \"0\"`, `result`, and the limits. Rejected or infeasible requests never trigger a paid fallback. This is a repeatable bounded free computation, not one free paid-size request per account. Full pack planning supports larger inputs at its published price and requires separate spending authorization.\n\nFor direct HTTP use, POST JSON to `/v1/preview/commerce.pack-plan`; the complete operation is in `/openapi.json` with `security: []`, an example body and response schemas. Its input schema is also in `/v1/content/index` under `freePreviews`. Do not include credentials. GET does not execute anything. Anonymous trial requests and repeats are aggregate activity, not unique agents, customers or sales.\n\n## Read an example through tools\n\nIf your client exposes tools but not resources, call `agent_utilities_example`:\n\n```json\n{\"name\":\"agent_utilities_example\",\"arguments\":{\"name\":\"commerce_pack_plan\"}}\n```\n\nThe result includes `chargedMicroUsd: \"0\"`, `executionPerformed: false` and `example`, with the same fixed input/output and provenance as the public JSON example. No API key is needed. This helps tools-only clients evaluate the format before funding; [Claude's API MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) currently documents tool-call support only. This is not a claim that every client or its paid authentication flow has been tested.\n\nChoose a name from the helper's input schema. It covers non-network tools in the selected category only. It rejects custom inputs, URLs and unlisted names; it reads an existing build artifact without running the paid handler, accessing payment storage or forwarding credentials. An unavailable artifact returns an error, not a synthetic success or paid fallback. This is a fixed demonstration, not a free custom-input trial or customer receipt.\n\n## Check credits without spending\n\nCall `agent_utilities_balance` with empty arguments `{}`. It uses the same private Authorization header as paid execution. The result includes `mode` (`live` or `test`), `balanceMicroUsd` as an exact decimal integer string, `chargedMicroUsd: \"0\"`, and `observedAt`. One million micro-dollar credits equals $1 of service credit. Account identifiers and credentials are omitted.\n\nThis read is free; it creates no account, checkout, reservation or debit and does not read USDC wallet balances. Missing, invalid, revoked or wrong-mode keys cannot retrieve a balance. Frozen accounts return an error. A balance is a snapshot, not a spending budget or guarantee that a later call will succeed. Other agents sharing the key may spend concurrently. Keep the per-call price ceiling and obtain spending approval even when sufficient funds appear available.\n\n## Prepare, approve, execute\n\n1. Call `agent_utilities_prepare` with a tool name and its input. This validates input and returns a new payment request ID and the current price. It does not execute, reserve funds or charge anything.\n2. Save the returned `tool` and complete `arguments` before sending a paid call. Submit a new prepared call within five minutes; the response includes its expiry. Check that the price and task are approved within your agent's spending budget.\n3. Call that returned tool with the exact returned arguments. The remote tool schema wraps the original payload in `input` and requires `requestId` and `maxPriceMicroUsd`.\n4. Save the receipt and recovery expiry from the result's `_meta`. A successful response includes `structuredContent` with the tool output.\n\nExample free preparation call:\n\n```json\n{\n  \"name\": \"agent_utilities_prepare\",\n  \"arguments\": {\n    \"name\": \"commerce_gtin_validate\",\n    \"input\": { \"code\": \"036000291452\" }\n  }\n}\n```\n\nThe response returns a `tool` and `arguments`; pass them to `tools/call`. The maximum is integer micro-dollar credits: 300 means $0.0003. A higher actual price is rejected before a new debit. The ceiling is per call; no total session budget is imposed.\n\n## Recover an uncertain call\n\nKeep the same tool, input and payment `requestId`. Change only `maxPriceMicroUsd` to `0`, then repeat within ten minutes of completion. This permits recovery of an existing result but rejects a new debit if the original never arrived. JSON-RPC IDs may change on reconnect; they are not payment identities. Recovery persists across client and worker restarts.\n\nDo not call prepare again after an uncertain result: it returns a new payment identity, which can create another debit. After recovery expires, check your balance and contact support before repeating work. If a changed input is sent with the same request ID, the ledger rejects it.\n\n## Transport and compatibility\n\nThis is a stateless Streamable HTTP endpoint using JSON responses. It supports initialization, ping, tool discovery/calls and resource discovery/reads. Clients must send `Accept: application/json, text/event-stream` and use the negotiated MCP protocol-version header. GET and DELETE return 405; there is no background SSE stream or server-managed MCP session. POST notifications return 202.\n\nOrigin-bearing requests must use this service's own origin; browser JavaScript from other origins is not supported. Server-to-server clients normally omit Origin. Malformed/oversized messages and unsupported protocol versions are rejected. Tool failures are returned as MCP error results without exposing credentials or internal transport exceptions.\n\nThe existing `/mcp` stateless JSON API and local adapters remain available with their existing input schemas. Use `/mcp/remote` for a hosted standard MCP transport; do not confuse the wrapped remote tool arguments with the local adapter's unwrapped arguments.\n\nImplementation follows the [MCP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) using the official TypeScript SDK. SDK and local workerd checks do not establish compatibility with every desktop client, marketplace or OAuth-only platform. Synthetic fixture credits and response-loss tests are not customer payments.\n\n## Optional shopping skill\n\n[Download the Agent Skills instruction file](https://agent-utilities.agent-utilities.workers.dev/downloads/agent-utilities-shopping-SKILL.md) to help a compatible client select shopping calculations and preserve payment retry identities. [Installation and checksum](https://agent-utilities.agent-utilities.workers.dev/integrations/mcp#skill). It does not configure a connection, supply credentials or grant spending permission. You may read the same instructions through the free `shopping-skill` MCP resource or `/v1/content/docs/shopping-skill`.\n\nMachine clients may also discover the instruction file at `/.well-known/agent-skills/index.json`. This follows [Cloudflare’s Agent Skills Discovery draft v0.2.0](https://github.com/cloudflare/agent-skills-discovery-rfc/blob/main/README.md), with a versioned schema identifier, direct Markdown URL and SHA-256 digest of the artifact bytes. Both index and artifact support GET/HEAD and public CORS. Verify the digest before loading instructions; the digest establishes consistency with this host, not independent publisher trust. This draft is not a universal client standard or automatic installation mechanism.\n\n## Check a raw HTTP connection without paying\n\nThe service-specific discovery documents at `/.well-known/mcp.json` and `/v1/content/index` now include `http` connection hints: request headers, initialization, initialized notification and tool-list messages. These hints supplement the MCP specification. They are not payment instructions or a new protocol.\n\nThis Node.js 22+ example needs no packages, account or wallet. It initializes the connection and lists tools; it never calls a tool. Use your own client name when integrating it.\n\n```sh\nnode --input-type=module <<'JS'\nconst endpoint = 'https://agent-utilities.agent-utilities.workers.dev/mcp/remote';\nconst headers = {'Content-Type':'application/json', Accept:'application/json, text/event-stream'};\nasync function post(message) {\n  const r = await fetch(endpoint, {method:'POST', headers, body:JSON.stringify(message), redirect:'error', signal:AbortSignal.timeout(15000)});\n  if (!r.ok) throw new Error(`MCP HTTP ${r.status}: ${await r.text()}`);\n  return r.status === 202 ? null : r.json();\n}\nconst hello = await post({jsonrpc:'2.0', id:1, method:'initialize', params:{protocolVersion:'2025-11-25', capabilities:{}, clientInfo:{name:'agent-utilities-connection-check', version:'1'}}});\nif (hello.error || !hello.result?.protocolVersion) throw new Error('MCP initialization failed');\nheaders['MCP-Protocol-Version'] = hello.result.protocolVersion;\nawait post({jsonrpc:'2.0', method:'notifications/initialized'});\nconst catalog = await post({jsonrpc:'2.0', id:2, method:'tools/list'});\nif (catalog.error || !Array.isArray(catalog.result?.tools)) throw new Error('MCP discovery failed');\nconsole.log(JSON.stringify({server:hello.result.serverInfo, tools:catalog.result.tools.map(t=>t.name), toolExecutionPerformed:false}, null, 2));\nJS\n```\n\nHTTP 406 with “Client must accept both” means the `Accept` header lacks one of the two required response types. Send the full header above, even though this service currently replies with JSON. HTTP 405 on GET means there is no background stream here; send the initialization POST. Neither response means you need to purchase credits. A directory's handshake failure does not establish which headers it sent; its operator must confirm the actual request.\n\n\n## Funding information inside your AI client\n\nCall `agent_utilities_payment_options` with `{}` to read the current $1 and $5 service-credit packs, live/test configuration, and funding link. It is free, needs no key, and creates no account or checkout. The same tool is available in every hosted category scope.\n\nUse a free preview or fixed example first, then `agent_utilities_prepare` to inspect the cost of the specific paid call. If you choose to buy credits, open the returned billing link and select a pack. Keep the credentials private and configure the API key in your client's Authorization header. Confirm funding through `agent_utilities_balance`; a checkout redirect alone is not proof that credits arrived. These are hosted MCP tools, not new functions in the separately versioned local adapter.\n\nA pack funds a balance; it is not the price of a single call. No subscription or automatic top-up is enabled. Clients that cannot set a private Authorization header can use free tools but cannot make paid service-credit calls.\n"}