Troubleshooting
Find what you are seeing, then the cause and the fix. Every error code is listed once, with its HTTP status, in the API reference’s errors table; this page is the “what do I do about it” side.
Two shapes of error come back from /mcp, and it helps to know which you have. A tool-level error (a bad argument, a rule the server cannot answer) is HTTP 200 with result.isError: true and an {"error":{"code":...}} object in content[0].text. A JSON-RPC error (a rate limit, a rejected key, a request the server cannot read) has a numeric error.code and usually a non-200 status. The REST routes return one {"error":{...}} object either way (details).
Rate limits (HTTP 429)
429 with a JSON-RPC error -32000 (REST: RATE_LIMIT)
Cause. Your own allowance is used up. error.data.scope says which one: window is the 5-minute window, daily is the UTC day. The allowance is per IP address with no key, shared across Claude’s connectors for calls that come through them, and per key with a key (the numbers). Only tools/call is counted: connecting, listing tools and reading resources never use it up.
Fix. Wait, then retry. Which header tells you how long depends on the limit:
- A 5-minute window, with or without a key: wait the
Retry-Afterseconds. - The daily allowance with no key:
Retry-Aftercounts down to UTC midnight. - A key’s daily allowance: there is no
Retry-After;X-Quota-Resetgives UTC midnight as Unix seconds.
If you hit the daily allowance regularly, a key gives you one of your own. Reference: errors table, headers.
429 with only {"message":"Too Many Requests"}
Cause. The shared limit on the whole API (about 100 requests a minute, shared by every caller), not your allowance. That is why it has no JSON-RPC body and no rate-limit headers.
Fix. Back off for a few seconds and retry, with growing gaps if it repeats. A key does not raise this limit (rate limits).
Keys
401 with -32001 (REST: UNAUTHORIZED)
Cause. You sent an Authorization header and the key in it is malformed, unknown, revoked or expired. error.data.reason says which: invalid_token, token_revoked or token_expired. The server never falls back to the anonymous allowance when a key is refused.
Fix. Check the header is exactly Authorization: Bearer <key>, with the whole key and no quotes or line breaks. A free key expires one year after it was created: create a new one. For a paid key, email us for a replacement. To use the anonymous allowance instead, remove the header. Reference: errors table.
My key is not being used
Cause. The client is not sending it. The npm package @markcolabs/mcp never sends a key, and Claude’s custom connectors cannot send this server’s key. Without rate-limit headers on a successful answer, the call was anonymous: every keyed answer carries them.
Fix. Connect over HTTP from a client that can send an Authorization header (which clients can).
Requests the server refuses
413 “Request body too large”
Cause. The request body is over 4 KB (4,096 bytes), on /mcp or the REST route. On /mcp it is a JSON-RPC error -32600 with "id": null; on REST it is INPUT_VALIDATION.
Fix. Send less: one JSON-RPC message per request (batches are not served), and no fields the tool does not take. A large money_flow_map budget is the call most likely to reach the limit; shorten its item names or group items. Reference: body size and JSON.
400 with -32700 (REST: “Body is not valid JSON”)
Cause. The body did not parse as JSON. From a terminal this is usually shell quoting: Windows cmd and PowerShell treat single quotes differently from bash.
Fix. Put the JSON in a file and send it with curl -d @body.json, or check the quoting for your shell.
415 with -32600 and unsupported_media_type
Cause. The request has a body but does not declare Content-Type: application/json. Some HTTP tools default to form encoding.
Fix. Add -H 'Content-Type: application/json' (a charset parameter is fine). Reference: headers.
403 with origin_not_allowed
Cause. The request carries an Origin header from a site other than https://www.digitalcalculator.info, which is what a browser sends from a web page.
Fix. Call the server from your backend, a command-line tool or an MCP client, not from browser code. Those leave Origin out. Reference: errors table.
Input errors
INPUT_VALIDATION naming a camelCase argument
Cause. Arguments are snake_case. An unknown argument is refused rather than ignored, so that a misspelling cannot quietly change an answer, and the message proposes the closest accepted name: "unknown argument 'annualReturnPercent' — did you mean 'annual_return_percent'?". field names the argument. Four tools (mortgage_monthly_payment, loan_monthly_payment, paycheck_net_pay, emergency_fund_recommendation) still accept their older camelCase spellings; every other tool does not. Sending both spellings of one argument with different values is also refused.
Fix. Use the name the message suggests, or the names in tools/list. The one place camelCase is right is the input object of generate_report. Other INPUT_VALIDATION messages say what is wrong in plain words: "<field> is required", "<field> must be a number", or the accepted range. Reference: unknown arguments, older names.
Unknown tool: <name>
Cause. The tool name is not one the server has. It is an INPUT_VALIDATION error. Tool names are snake_case (mortgage_monthly_payment); the dot-separated names of the old 0.2.x package (dc.calculator.mortgage.monthlyPayment) were retired.
Fix. Call tools/list and use a name from it. If the missing tool is generate_report, see below. Reference: the tools.
BUSINESS_RULE on a rule_year: 2027 call
Cause. The call asked for the 2027 rules, and the answer needs a 2027 figure the server does not hold yet. The message names the missing figures, and field is rule_year.
Fix. Use rule_year: 2026, or leave rule_year out (2026 is the default), or ask again once the figures are published. Reference: errors table.
Reports
authentication_required from generate_report, or the tool is missing
Cause. generate_report needs a paid dc_bearer_ key. With no key or a free dc_pub_ key it is left out of tools/list, and calling it anyway returns authentication_required.
Fix. Send a paid key (getting one, using reports).
report_quota_exceeded, rate_limited or REPORT_UNAVAILABLE
Cause. report_quota_exceeded: the key’s daily report quota is used up. rate_limited: the key’s 5-minute window, which reports share with calculator calls, is full. REPORT_UNAVAILABLE: the tool you named has no report.
Fix. Retry after UTC midnight for the daily quota, or once the 5-minute window resets. For REPORT_UNAVAILABLE, use one of the aliases the message lists. Reference: generate_report errors.
Connecting
The client cannot connect, or the server shows no tools
Cause. Usually the URL or the transport. The server answers only a POST to exactly https://mcp.digitalcalculator.info/mcp, over the Streamable HTTP transport. Anything else, including a GET, the URL without /mcp, or a client set to the older SSE transport, gets 404 Not Found.
Fix.
- Check the URL ends in
/mcpand starts withhttps://mcp.(api.digitalcalculator.infois the REST host and has no/mcp). - Choose the “HTTP” or “Streamable HTTP” transport, not SSE. If your client speaks only stdio, use the npm package.
- In claude.ai or Claude Desktop, check the connector is switched on in the conversation’s tools menu. If you filled in the connector’s authentication fields, remove it and add it again with them blank: this server has no sign-in to complete.
- Test the endpoint on its own with
curland atools/listrequest (example), or with MCP Inspector.
Client-by-client steps are in the quickstart.
The npm package will not start
Cause. @markcolabs/mcp needs Node.js 18 or later. On an older Node, npx warns about an unsupported engine and the package may fail to start.
Fix. Run node --version and upgrade to Node.js 18 or later. If your client launches the package itself, make sure it finds that Node, not an older one on another path.
“Request timed out after 30s” from the npm package
Cause. The package gives each request 30 seconds to reach the hosted server and answer. A timeout means the request did not get through in time, usually a network problem between you and the server.
Fix. Retry. If it keeps happening, try the endpoint directly with curl to see whether the network or the server is the problem, and check the status page.
Still stuck?
Email admin@markcolabs.com with the request you sent (with any key removed), the full response, and the time. Please report every INTERNAL error (HTTP 500, -32603 on /mcp). The FAQ covers questions that are not errors.