PHOENIX MCP GATEWAY: INSTRUCTIONS FOR AUTONOMOUS AGENTS Gateway version 0.1.0. Generated from the live catalog on 2026-09-20. Free to read, no authentication needed. Everything below describes what is routable now. 1. ENDPOINT POST https://gateway.mcpharbor.dev/mcp Transport: MCP Streamable HTTP, one JSON-RPC request per POST. POST https://gateway.mcpharbor.dev/mcp/ narrows the endpoint to a single upstream server. Send with every POST: Content-Type: application/json Accept: application/json, text/event-stream The response is either application/json or a text/event-stream SSE stream; handle both. 2. PROTOCOL VERSIONS Modern (stateless, no initialize handshake): 2026-07-28 Legacy (initialize handshake, Mcp-Session-Id): 2025-11-25, 2025-06-18, 2025-03-26 On a modern request, params._meta MUST carry both of these keys: "io.modelcontextprotocol/protocolVersion" "io.modelcontextprotocol/clientCapabilities" Omit either one and the request is refused with JSON-RPC -32602 and HTTP 400. Every POST MUST also carry these headers: MCP-Protocol-Version: Mcp-Method: Mcp-Name: (required on tools/call) Error codes you may see: -32020 HeaderMismatch a header disagrees with the body (HTTP 400) -32021 MissingRequiredClientCapability a needed client capability was not declared -32022 UnsupportedProtocolVersion retry with one of the versions above (HTTP 400) Modern results always carry "resultType": "complete". 3. AUTHENTICATION Authorization: Bearer Required on every request to the MCP endpoint, including the free ones, because the key identifies the account whose balance a tools/call draws down. A missing, unknown or revoked key is refused with HTTP 401. Keys are stored hashed: a lost key cannot be recovered, only replaced. The documentation and registry URLs in section 12 need no key at all. 4. WHAT IS FREE AND WHAT IS CHARGED FREE, never billed: server/discover, tools/list, registry endpoints, docs files. FREE and unauthenticated: llms.txt, llms-full.txt, agent.txt, skill.txt, server.json and every /docs page. CHARGED: tools/call, and only tools/call. A tools/call is charged once it reaches the upstream and the upstream returns a result. That includes a result carrying "isError": true from the upstream: a provider that comes back with "no such city" or "date out of range" did the work and handed you something to correct against, and it costs the same as an answer you liked. NOT charged: anything refused before the upstream is contacted (an unknown tool, a malformed or mis-headered request, 402, 429), and a call whose upstream never returned a result at all - timeout, upstream unavailable, or a protocol error. That last kind is charged and then refunded inside the same request; see section 10. Careful: the gateway reports those upstream failures to you as a result with "isError": true as well, so "isError" on its own does not tell you whether you paid. The call record in section 6 does. 5. PRICE 100 micro-USD per tool call = $0.0001 USD. 1 micro-USD = $0.000001. Balances, charges and refunds are whole micro-USD integers, so nothing is ever rounded away. Billed on: each tools/call that reaches the upstream and returns a result. 6. BILLING MODEL, CALL IDS, AND WHAT IDEMPOTENCY YOU ACTUALLY GET Billing model: prepaid credits, drawn down per call. Top up a balance, and each charged call draws 100 micro-USD from it. The balance check and the charge happen BEFORE the upstream is contacted: a call you cannot afford never reaches the provider. Every charged call gets a call id, and the result carries it back to you: "_meta": { "dev.mcpharbor.gateway/call": { "id": "", "chargedMicroUsd": 100 } } The gateway attaches that record to charged calls and to nothing else, so its presence is how you tell a billed result from a free one. Keep the id with whatever you did with the result: it is the ledger's key for that charge, and it is what an automatic refund (section 10) reverses. The ledger is append-only and a given call id can be charged only once. Be precise about what that does and does not buy you, because it is not request idempotency: the gateway mints a fresh call id for every POST it accepts, so two POSTs are two ids and two charges even when the two requests are byte-for-byte identical. This revision of the protocol has no client-supplied idempotency key, and the gateway offers none of its own. Read section 7 before you retry anything. 7. RETRYING SAFELY The gateway cannot tell a retry from a new call, so whether retrying costs you anything depends entirely on how the first attempt ended. SAFE to repeat unchanged - the first attempt cost nothing: - HTTP 400: a protocol or header problem (-32020, -32022, or -32602 for a missing params._meta key). Fix the request first; an identical retry fails identically. - HTTP 401: nothing runs without a valid key. - HTTP 402: see section 8. Top up first. - HTTP 429: see section 9. Wait out Retry-After first. - HTTP 200 carrying a JSON-RPC error instead of a result (an unknown tool, arguments the upstream rejected). Nothing was charged, or a charge was already refunded. - HTTP 200 with a result that has no call record in its _meta: the upstream returned nothing and the charge was refunded in that same request. NOT SAFE to repeat - you will pay again: - HTTP 200 with a call record. That call is paid for and done, including when the result said "isError": true. Sending it again buys a second call at 100 micro-USD. - No response at all. A client timeout, a dropped connection or a proxy reset tells you nothing about what happened at this end: the call may well have been charged and completed, and its call id went missing along with the response. Repeat it and the gateway mints a second id, writes a second charge, and calls the provider again. The gateway exposes no endpoint for asking, after the fact, whether a particular attempt was charged, so a lost response cannot be reconciled from your side. Repeat one only when repeating it is harmless anyway - a read-only lookup, or a tool whose tools/list annotations declare "idempotentHint": true - and when paying 100 micro-USD twice is an acceptable price for the answer. Otherwise treat the call as done and move on. 8. HTTP 402 PAYMENT REQUIRED Meaning: your balance cannot cover this call (100 micro-USD). Nothing was charged and no upstream was contacted, so the call had no effect anywhere. Recover: top the account up, then repeat the identical request. Retrying before topping up cannot succeed. Free operations keep working at a zero balance, so you can still discover tools while out of credit. The JSON-RPC error carries code 402, and its data carries your balance and the price. 9. HTTP 429 TOO MANY REQUESTS Meaning: you went over the per-account rate limit. The call was not charged. The response carries a Retry-After header. Its value is delta-seconds (RFC 9110): a whole number of seconds to wait, rounded up. The JSON-RPC error data repeats the same delay as "retryAfterMs", in milliseconds. Wait at least that long and then repeat the same request. Do not retry sooner and do not open more connections: the limit is per account, not per connection. Per-upstream limits exist too and are there to keep us inside each provider's free tier. The JSON-RPC error carries code 429. 10. REFUNDS If a charged call then fails upstream (timeout, upstream unavailable, or a protocol error), the charge is refunded to your balance automatically, inside the same request. The gateway does this on its own; there is nothing for you to call and nothing to claim. Refunds are idempotent per call id, so you are never refunded twice and never left paying for a call that returned no result. You pay only for each tools/call that reaches the upstream and returns a result. 11. WORKED EXAMPLE: ONE PAID TOOL CALL `arxiv__arxiv_get_metadata` below is a real entry in this catalog, from arXiv. Substitute any tool name that tools/list returns. --- request --- POST /mcp HTTP/1.1 Host: gateway.mcpharbor.dev Authorization: Bearer Content-Type: application/json Accept: application/json, text/event-stream MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: arxiv__arxiv_get_metadata { "id": 1, "jsonrpc": "2.0", "method": "tools/call", "params": { "_meta": { "io.modelcontextprotocol/clientCapabilities": {}, "io.modelcontextprotocol/clientInfo": { "name": "example-agent", "version": "1.0.0" }, "io.modelcontextprotocol/protocolVersion": "2026-07-28" }, "arguments": { "paper_ids": "example" }, "name": "arxiv__arxiv_get_metadata" } } --- response --- HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "_meta": { "dev.mcpharbor.gateway/call": { "chargedMicroUsd": 100, "id": "" } }, "content": [ { "text": "", "type": "text" } ], "resultType": "complete" } } That exchange costs $0.0001 (100 micro-USD), and the call record in the result's _meta is the receipt for it. The same request without the "io.modelcontextprotocol/clientCapabilities" key in params._meta would have been refused with -32602 and HTTP 400, and would have cost nothing. 12. FINDING TOOLS tools/list on the endpoint above returns every routable tool, cursor-paginated, for free. https://gateway.mcpharbor.dev/llms.txt index of this gateway https://gateway.mcpharbor.dev/llms-full.txt every tool with parameters, price and attribution https://gateway.mcpharbor.dev/skill.txt task recipes with their total cost https://gateway.mcpharbor.dev/server.json registry-format description of this gateway https://gateway.mcpharbor.dev/v0.1/servers MCP Registry API, cursor-paginated https://gateway.mcpharbor.dev/docs/servers/ and https://gateway.mcpharbor.dev/docs/tools/ Catalog right now: 16 servers, 139 tools. 13. ATTRIBUTION Some providers require an attribution string wherever their data is used. Reproduce it verbatim in anything you produce from these tools: - arXiv (arxiv): Thank you to arXiv for use of its open access interoperability. (requested, not required) - US Bureau of Labor Statistics (bls): "BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov", plus cite BLS as source - Frankfurter (ECB rates) (frankfurter): None required by Frankfurter itself; underlying ECB source requires citing ECB as source and, if resold, telling buyers the data is free elsewhere. - NASA Open APIs (nasa): NASA should be acknowledged as the source of the material - NOAA Tides & Currents (noaa_marine): NOS requests attribution whenever its material is reproduced and re-disseminated; content must not be modified and presented as official government material; predictions are forecast guidance, not ... - US National Weather Service (nws): No attribution required. Must not claim the content as your own, imply NOAA/NWS endorsement, or modify content and present it as official government material. Third parties producing copyrighted wo... - OpenAlex (openalex): Appreciated but not required (CC0) - PubChem (pubchem): Attribution to source recommended, not mandatory - PubMed (pubmed): NCBI's Disclaimer and Copyright notice must be evident to users of your product - US Treasury FiscalData (treasury): Not stated as required - USGS Earthquakes (usgs_quake): Not legally required (public domain), but USGS asks that proper credit be given, e.g. 'Credit: U.S. Geological Survey, Department of the Interior/USGS'. Do not imply USGS endorsement. - World Bank (worldbank): "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees