Moltline Studio Get a license

Blog

HTTP 402 vs Entitlement Errors on Premium MCP Tools

Professional header image for educational tutorial: Premium Tool Returns Entitlement Error, Not HTTP 402
EP=https://mcp.moltlinestudio.com/catalog
H='Accept: application/json, text/event-stream'
J='Content-Type: application/json'
INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'
curl -sS -D headers.txt -o /dev/null -X POST "$EP" -H "$J" -H "$H" -d "$INIT"
SID=$(grep -i '^mcp-session-id' headers.txt | awk '{print $2}' | tr -d '[:space:]')
curl -sS -X POST "$EP" -H "$J" -H "$H" -H "mcp-session-id: $SID" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -sS -X POST "$EP" -H "$J" -H "$H" -H "mcp-session-id: $SID" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_full_kit","arguments":{"slug":"kit-developer-starter"}}}'

Open a session (Moltline's servers need initialize first), call a premium tool on one of the 22 servers without an entitlement, and the tool result comes back with premium_tool_requires_license in its error field. It is not an HTTP 402. That single mismatch produces most of the confused agent logs you will debug this week.

Two error surfaces get conflated. The licence check fires on the tool call, after the agent already reached the tool and only lacks entitlement. The payment challenge fires on the payment endpoint, before anything has been bought. A live x402 challenge returns HTTP 402 with an amount, currency, and destination. Different layers, different handlers, different branches.

The 110 free forever tools never touch either path; the other 50 sit behind the $19/mo All-Access licence, paid in USDC on Base.

Why Does One Tool Call Produce Two Different Error Bodies?

Call a premium tool on mcp.moltlinestudio.com/<server> in a session with no license and you get HTTP 200 with a normal tool result, not HTTP 402 and not a JSON-RPC error object. This is the catalog server's get_full_kit, trimmed:

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{...}"}],"structuredContent":{"error":"premium_tool_requires_license","tool":"get_full_kit","message":"...","upgrade_url":"https://moltlinestudio.com/#allaccess","price":{...},"x402":{"resource":"https://moltlinestudio.com/api",...},"x402_day_pass":{"resource":"https://moltlinestudio.com/api/premium/day-pass",...}},"isError":false}}

Now ask for payment on the payment host. The payment endpoint answers with an HTTP 402 carrying an x402 challenge:

$ curl -i https://moltlinestudio.com/api
HTTP/2 402

Run that call yourself to read the live challenge. A handler that conflates the two layers retries a failure it can never fix.

The trap is one host path: mcp.moltlinestudio.com/api does not exist. Payment lives at moltlinestudio.com/api.

To separate transport faults from entitlement, call any free server in the catalog at our MCP server list. All 110 free tools answer with no error, which proves the host is reachable and the missing piece is the license alone.

Once that control call is clean, wire the split into your Claude client wiring at the Claude integration walkthrough, where the two paths diverge in practice.

What Does HTTP 402 Mean in the HTTP Spec?

402 is defined, barely. RFC 2068 first reserved the code in January 1997. RFC 9110, published June 2022, still reserves it for future use and names no payment method (RFC 9110 ยง15.5.3). A bare 402 proves nothing about x402, so read the API's own docs and response body before assuming a challenge. x402 supplies the missing meaning: it asks for payment with an amount, a currency, and a destination (x402 docs).

Timeline, two sentences: Coinbase announced x402 on May 6, 2025. The Linux Foundation announced the x402 Foundation in April 2026, and it became operational that July (Linux Foundation).

If you are mapping this onto what breaks in agent licensing, the licence layer follows the same rule: the status alone never tells you the fix.

What Does a Premium Tool Return Without a Licence?

Moltline Studio runs 22 hosted MCP servers and 160 tools. Of those, 110 are free forever, with no account, API key, or signup. The remaining 50 sit behind the All-Access license.

Pick one of the 50 from the premium server listing and call it in a session without a license. The tool result's error field is premium_tool_requires_license, with upgrade_url pointing at the licence page and an x402 block pointing at moltlinestudio.com/api. That behavior belongs to the endpoint, so do not hunt for it in RFC 9110.

It is not an HTTP 402 because nothing failed at the edge. The request reached the tool and cleared transport and auth. The agent simply holds no entitlement.

Nothing was attempted and nothing was quoted: no charge, no price, no settlement step. Retrying changes nothing, because the response is deterministic.

If you are weighing how much of a stack should live in MCP at all, our community thread on stack tradeoffs works through it. The surface that does quote a price is a separate endpoint.

What Does the x402 Payment Endpoint Return?

The tool call never quoted a price; the payment endpoint does. Run curl -i https://moltlinestudio.com/api with no payment and you get HTTP 402 carrying an x402 challenge: amount, currency and destination address, in the body or headers. Read the version field before you parse anything else.

V2 moves that data into headers: PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE, documented in the x402 HTTP 402 spec. Do not read V1 body fields and V2 headers in the same handler.

Prices are fixed per purchase, never per call:

  • 19 USDC on Base at moltlinestudio.com/api for one month

  • 2 USDC at moltlinestudio.com/api/premium/day-pass for a day pass to the end of the next UTC day

Crypto only. This 402 is a quote for one purchase, not a metered call. Pay it once and the entitlement error disappears from every tool the licence covers, including the premium servers in the catalog. For a worked handler that splits this path from the tool-call error, see the 402 handling walkthrough.

How Do the Two Errors Compare Side by Side?

The two surfaces differ at every column that matters:

Status

Host

Layer

Body contents

What it means

Retryable

Handler action

200, tool result (not a JSON-RPC error)

mcp.moltlinestudio.com/<server>

Tool call, entitlement check

error field premium_tool_requires_license, plus upgrade_url and an x402 pointer to moltlinestudio.com/api

The tool was reached; the agent holds no licence

No

Surface the pointer, or pay

HTTP 402

moltlinestudio.com/api or /api/premium/day-pass

Payment endpoint

An x402 challenge with an amount, an asset and a destination

A quote, not a fault

No (pay or stop)

Parse the version, then sign

HTTP 402

Third-party API

Account billing

Vendor-specific code, no challenge

Not an x402 challenge

No

Hand it to the account owner

The licence check fires on any premium tool call; the challenge fires only where a purchase can actually be made. Test each layer in isolation before you write the branch, which is exactly what an agent-readiness score separates.

How Should a Handler Branch on the Error Body?

Read the status, then the body, then decide. A tool-call entitlement failure and a purchase quote do not share a host, so status alone cannot pick the branch.

function handle(res, body, host) {
 const code = body?.result?.structuredContent?.error ?? body?.error?.code;
 log.info({ host, status: res.status, code });

 if (code === 'premium_tool_requires_license') {
 return { action: 'stop', licence: 'https://moltlinestudio.com/api' };
 }

 if (res.status === 402) {
 const v = body?.x402Version ?? res.headers['payment-required'];
 if (!v) return { action: 'unknown_402' };
 return { action: 'sign', version: v };
 }

 return { action: 'billing' };
}

Check order:

  1. Read host and status.

  2. Read the error code string.

  3. On 402, read the x402 version.

  4. Pick the path and log all of it.

Never parse accepts on a tool-call error body. It will not be there, and a parser that assumes it will produces a null-price bug.

Log the host plus the error code, not the bare status. A grep for 402 http misses every entitlement failure, which is how this confusion starts.

Confirm the branch against a free MCP server first, then the MCP transport and setup basics if the host itself looks wrong.

Which APIs Return 402 for Billing, Not Payment?

Your branch now falls through to a generic billing case, and that case is not one thing. Per qday.io, these APIs return 402 for billing rather than payment:

  • Stripe: a failed charge

  • Shopify: a frozen shop

  • Google: quota or payment due

  • DeepSeek: an empty balance

  • OpenRouter: an empty balance

None of these is an x402 challenge. A handler that signs on every 402 will try to pay an account state the agent cannot fix.

Put the set in a comment so the next maintainer does not rediscover it:

// 402 without x402 challenge: Stripe charge failed, Shopify frozen,
// Google quota/payment due, DeepSeek/OpenRouter empty balance.
// Do not sign. Surface to human.

The rule: sign only when the response carries a parseable challenge with an amount, an asset, and a destination. For routing those branches across MCP tools, see Claude Code Router.

Why You Should Not Retry an Entitlement Error?

That third-party billing case is also not retryable, and neither is the entitlement error. A call that returns premium_tool_requires_license is deterministic: the licence check runs again, finds no entitlement, and returns the same code. No retry count creates a licence.

Retry loops cost you twice. They spend your own rate budget, and they bury the real fault in noise, which is how the same bug gets reported twice.

Retry only transport failures, such as a reset connection or a 5xx, and payment submissions that came back without a valid challenge. Do not retry an entitlement failure.

Instead:

  • Read the pointer in the error body.

  • Hand the human the URL.

  • Or let the agent pay at the payment endpoint if it holds USDC on Base.

The studio sends a first reply within 24h and fixes confirmed defects within 30 days. There is no SLA, and support cannot grant a licence that was never sold.

Which Three Mistakes Send Handlers Back to the Same Bug?

Retrying is one symptom. Three mistakes keep sending handlers back to the same bug.

  1. Calling mcp.moltlinestudio.com/api. That host path does not exist. Payment is at moltlinestudio.com/api.

  2. Treating premium_tool_requires_license as an HTTP 402. The tool call returns an HTTP 200 tool result with that code in its error field. Retrying without a licence key does not change it.

  3. Mixing V1 body fields with V2 headers. The version split only matters on the payment endpoint. Check the version first, then parse one shape, per bmdpat's correction note.

The sanity test catches all three: call a free tool, then the premium tool, then the payment endpoint, and log the three bodies exactly as shipped.

Three hosts, three distinct shapes, no shared status. Run that once and the branch in your handler has nothing left to guess at.

What to Check First in Your Agent Log

Grep your logs for premium_tool_requires_license and for 402 as two separate queries. If premium_tool_requires_license and 402 never appear against different hosts, your client is collapsing the two surfaces before you see them.

What to Check First in Your Agent Log
What to Check First in Your Agent Log

Then run this once and keep the output:

curl -i https://moltlinestudio.com/api

That body is what an x402 challenge looks like on this service. Compare it byte for byte against your captured tool-call error.

Conclusion

Your next step: run the three-call sanity test once, a free tool, the premium tool, then /api, and log each body exactly as shipped. Compare them byte for byte, then read the licence pointer the tool call returns and decide whether a human pays at /api or an agent settles over x402 in USDC on Base. Three bodies, three paths, no guessing left in your handler.