Developer Docs: API and MCP
Hesaplayıcı
Every Hesaplayıcı calculator also works through the JSON API that the page form uses, and connects to AI clients such as Claude, ChatGPT or Cursor as an MCP server. Free tools need no account and no key; requests are limited per IP address. Every answer returns the result, the calculation steps and the tool page URL to cite.
Quick start
Two HTTP requests are enough to list the tools and run one. The list request gives the id, name and version of every tool. The run request checks the input object against the tool’s schema and returns the result, the steps and the URL to cite. The answer below is the example that runs for real in every build of the site.
List every tool:
curl https://hesaplayici.com/api/v1/toolsRun Compound Interest Calculator with its first example:
curl -X POST https://hesaplayici.com/api/v1/tools/finance.compound-interest/execute \
-H 'Content-Type: application/json' \
-d '{"input":{"principal":10000,"rate":10,"rateUnit":"yearly","years":5,"months":0,"weeks":0,"days":0,"compounding":"monthly"},"locale":"en"}'Answer:
{
"output": {
"finalAmount": 16453.089347785855,
"interestEarned": 6453.089347785855,
"annualRate": 10,
"effectiveRate": 10.471306744129683,
"termYears": 5,
"yearly": [
{
"period": 0,
"interest": 0,
"accruedInterest": 0,
"balance": 10000
},
{
"period": 1,
"interest": 1047.1306744129688,
"accruedInterest": 1047.1306744129688,
"balance": 11047.130674412969
},
{
"period": 2,
"interest": 1156.7789393426228,
"accruedInterest": 2203.9096137555916,
"balance": 12203.909613755592
},
{
"period": 3,
"interest": 1277.908810432682,
"accruedInterest": 3481.8184241882736,
"balance": 13481.818424188274
},
{
"period": 4,
"interest": 1411.7225618833454,
"accruedInterest": 4893.540986071619,
"balance": 14893.540986071619
},
{
"period": 5,
"interest": 1559.5483617142363,
"accruedInterest": 6453.089347785855,
"balance": 16453.089347785855
}
],
"monthly": [
{
"period": 0,
"interest": 0,
"accruedInterest": 0,
"balance": 10000
},
{
"period": 1,
"interest": 83.33333333333394,
"accruedInterest": 83.33333333333394,
"balance": 10083.333333333334
},
{
"period": 2,
"interest": 84.02777777777737,
"accruedInterest": 167.3611111111113,
"balance": 10167.361111111111
},
{
"period": 3,
"interest": 84.7280092592573,
"accruedInterest": 252.08912037036862,
"balance": 10252.089120370369
},
{
"period": 4,
"interest": 85.43407600308637,
"accruedInterest": 337.523196373455,
"balance": 10337.523196373455
},
{
"period": 5,
"interest": 86.14602663644655,
"accruedInterest": 423.66922300990154,
"balance": 10423.669223009902
},
{
"period": 6,
"interest": 86.86391019174698,
"accruedInterest": 510.5331332016485,
"balance": 10510.533133201649
},
{
"period": 7,
"interest": 87.5877761100146,
"accruedInterest": 598.1209093116631,
"balance": 10598.120909311663
},
{
"period": 8,
"interest": 88.31767424426289,
"accruedInterest": 686.438583555926,
"balance": 10686.438583555926
},
{
"period": 9,
"interest": 89.05365486296796,
"accruedInterest": 775.492238418894,
"balance": 10775.492238418894
},
{
"period": 10,
"interest": 89.79576865348827,
"accruedInterest": 865.2880070723822,
"balance": 10865.288007072382
},
{
"period": 11,
"interest": 90.54406672560435,
"accruedInterest": 955.8320737979866,
"balance": 10955.832073797987
},
{
"period": 12,
"interest": 91.2986006149822,
"accruedInterest": 1047.1306744129688,
"balance": 11047.130674412969
},
{
"period": 13,
"interest": 92.05942228677304,
"accruedInterest": 1139.1900966997418,
"balance": 11139.190096699742
},
{
"period": 14,
"interest": 92.82658413916579,
"accruedInterest": 1232.0166808389076,
"balance": 11232.016680838908
},
{
"period": 15,
"interest": 93.6001390069905,
"accruedInterest": 1325.6168198458981,
"balance": 11325.616819845898
},
{
"period": 16,
"interest": 94.38014016538182,
"accruedInterest": 1419.99696001128,
"balance": 11419.99696001128
},
{
"period": 17,
"interest": 95.16664133342601,
"accruedInterest": 1515.163601344706,
"balance": 11515.163601344706
},
{
"period": 18,
"interest": 95.95969667787358,
"accruedInterest": 1611.1232980225795,
"balance": 11611.12329802258
},
{
"period": 19,
"interest": 96.75936081685359,
"accruedInterest": 1707.8826588394331,
"balance": 11707.882658839433
},
{
"period": 20,
"interest": 97.56568882366082,
"accruedInterest": 1805.448347663094,
"balance": 11805.448347663094
},
{
"period": 21,
"interest": 98.37873623052656,
"accruedInterest": 1903.8270838936205,
"balance": 11903.82708389362
},
{
"period": 22,
"interest": 99.1985590324457,
"accruedInterest": 2003.0256429260662,
"balance": 12003.025642926066
},
{
"period": 23,
"interest": 100.02521369105125,
"accruedInterest": 2103.0508566171175,
"balance": 12103.050856617117
},
{
"period": 24,
"interest": 100.85875713847418,
"accruedInterest": 2203.9096137555916,
"balance": 12203.909613755592
},
{
"period": 25,
"interest": 101.69924678129792,
"accruedInterest": 2305.6088605368896,
"balance": 12305.60886053689
},
{
"period": 26,
"interest": 102.54674050447284,
"accruedInterest": 2408.1556010413624,
"balance": 12408.155601041362
},
{
"period": 27,
"interest": 103.4012966753453,
"accruedInterest": 2511.5568977167077,
"balance": 12511.556897716708
},
{
"period": 28,
"interest": 104.2629741476394,
"accruedInterest": 2615.819871864347,
"balance": 12615.819871864347
},
{
"period": 29,
"interest": 105.1318322655352,
"accruedInterest": 2720.9517041298823,
"balance": 12720.951704129882
},
{
"period": 30,
"interest": 106.00793086774866,
"accruedInterest": 2826.959634997631,
"balance": 12826.959634997631
},
{
"period": 31,
"interest": 106.89133029164623,
"accruedInterest": 2933.850965289277,
"balance": 12933.850965289277
},
{
"period": 32,
"interest": 107.78209137741032,
"accruedInterest": 3041.6330566666875,
"balance": 13041.633056666687
},
{
"period": 33,
"interest": 108.680275472223,
"accruedInterest": 3150.3133321389105,
"balance": 13150.31333213891
},
{
"period": 34,
"interest": 109.58594443448783,
"accruedInterest": 3259.8992765733983,
"balance": 13259.899276573398
},
{
"period": 35,
"interest": 110.49916063811179,
"accruedInterest": 3370.39843721151,
"balance": 13370.39843721151
},
{
"period": 36,
"interest": 111.41998697676354,
"accruedInterest": 3481.8184241882736,
"balance": 13481.818424188274
},
{
"period": 37,
"interest": 112.34848686823534,
"accruedInterest": 3594.166911056509,
"balance": 13594.166911056509
},
{
"period": 38,
"interest": 113.284724258805,
"accruedInterest": 3707.451635315314,
"balance": 13707.451635315314
},
{
"period": 39,
"interest": 114.22876362762509,
"accruedInterest": 3821.680398942939,
"balance": 13821.680398942939
},
{
"period": 40,
"interest": 115.18066999119037,
"accruedInterest": 3936.8610689341294,
"balance": 13936.86106893413
},
{
"period": 41,
"interest": 116.14050890778526,
"accruedInterest": 4053.0015778419147,
"balance": 14053.001577841915
},
{
"period": 42,
"interest": 117.1083464820149,
"accruedInterest": 4170.10992432393,
"balance": 14170.10992432393
},
{
"period": 43,
"interest": 118.08424936936717,
"accruedInterest": 4288.194173693297,
"balance": 14288.194173693297
},
{
"period": 44,
"interest": 119.0682847807766,
"accruedInterest": 4407.262458474073,
"balance": 14407.262458474073
},
{
"period": 45,
"interest": 120.0605204872827,
"accruedInterest": 4527.322978961356,
"balance": 14527.322978961356
},
{
"period": 46,
"interest": 121.06102482467941,
"accruedInterest": 4648.3840037860355,
"balance": 14648.384003786035
},
{
"period": 47,
"interest": 122.06986669821526,
"accruedInterest": 4770.453870484251,
"balance": 14770.45387048425
},
{
"period": 48,
"interest": 123.08711558736832,
"accruedInterest": 4893.540986071619,
"balance": 14893.540986071619
},
{
"period": 49,
"interest": 124.11284155059548,
"accruedInterest": 5017.6538276222145,
"balance": 15017.653827622215
},
{
"period": 50,
"interest": 125.14711523018377,
"accruedInterest": 5142.800942852398,
"balance": 15142.800942852398
},
{
"period": 51,
"interest": 126.19000785710341,
"accruedInterest": 5268.990950709502,
"balance": 15268.990950709502
},
{
"period": 52,
"interest": 127.24159125591177,
"accruedInterest": 5396.2325419654135,
"balance": 15396.232541965413
},
{
"period": 53,
"interest": 128.30193784971198,
"accruedInterest": 5524.534479815125,
"balance": 15524.534479815125
},
{
"period": 54,
"interest": 129.371120665126,
"accruedInterest": 5653.905600480251,
"balance": 15653.905600480251
},
{
"period": 55,
"interest": 130.4492133373351,
"accruedInterest": 5784.354813817587,
"balance": 15784.354813817587
},
{
"period": 56,
"interest": 131.5362901151475,
"accruedInterest": 5915.891103932734,
"balance": 15915.891103932734
},
{
"period": 57,
"interest": 132.6324258661025,
"accruedInterest": 6048.5235297988365,
"balance": 16048.523529798837
},
{
"period": 58,
"interest": 133.7376960816582,
"accruedInterest": 6182.261225880495,
"balance": 16182.261225880495
},
{
"period": 59,
"interest": 134.8521768823357,
"accruedInterest": 6317.11340276283,
"balance": 16317.11340276283
},
{
"period": 60,
"interest": 135.9759450230249,
"accruedInterest": 6453.089347785855,
"balance": 16453.089347785855
}
],
"truncated": false
},
"steps": [
{
"id": "annualRate",
"formula": "r = rate × periods per year",
"substitution": "r = 10% × 1",
"value": 10,
"unit": "%"
},
{
"id": "termYears",
"formula": "t = years + months/12 + weeks/52 + days/365",
"substitution": "t = 5 + 0/12 + 0/52 + 0/365",
"value": 5,
"unit": "years"
},
{
"id": "finalAmount",
"formula": "A = P × (1 + r/n)^(n × t)",
"substitution": "A = 10,000 × (1 + 10%/12)^(12 × 5)",
"value": 16453.089347785855
},
{
"id": "effectiveRate",
"formula": "e = (1 + r/n)^n − 1",
"substitution": "e = (1 + 10%/12)^12 − 1",
"value": 10.471306744129683,
"unit": "%"
}
],
"meta": {
"toolVersion": "1.0.0",
"locale": "en"
},
"citation": {
"url": "https://hesaplayici.com/en/finance/compound-interest-calculator",
"title": "Compound Interest Calculator"
}
}Authentication
Today free tools are used anonymously; a request needs no credentials. API keys, and OAuth for MCP, come with paid tools. Then a key is sent in the Authorization: Bearer header; a cookie is never used.
Rate limits
Each IP address can run a limited number of calculations per minute. Only run requests count: execute in REST and tools/call in MCP. List, schema and resource reads do not count. Every answer states the limit and what is left in its headers.
Anonymous requests: 60 calculations per 60 seconds per IP address.
| Header | Description |
|---|---|
X-RateLimit-Limit | Calculations allowed in the window |
X-RateLimit-Remaining | Calculations left in the window |
X-RateLimit-Reset | When the window resets (Unix seconds) |
Retry-After | Only on a 429 answer: seconds to wait before a retry |
Over the limit, the answer has status 429:
{
"type": "about:blank",
"title": "Too Many Requests",
"status": 429,
"code": "rate_limited",
"detail": "Rate limit reached. Try again after Retry-After seconds."
}Errors
Errors are RFC 9457 problem details (application/problem+json). Every error has a stable code field. For input errors, the errors array tells which field was rejected and why; an unknown input field is an error too. In MCP the same object comes in the structuredContent of a result marked isError.
MCP
The gateway server reaches every tool with three tools: search_tools finds a tool, get_tool returns its schema and run_tool runs it. The category servers expose each tool of their category directly, with its own schema. Tool pages and guides can also be read as Markdown resources.
| Server | URL |
|---|---|
| Gateway (every tool) | https://hesaplayici.com/mcp |
| Finance | https://hesaplayici.com/mcp/finance |
| Health | https://hesaplayici.com/mcp/health |
| Housing | https://hesaplayici.com/mcp/housing |
| Salary & Work | https://hesaplayici.com/mcp/labor |
| Math | https://hesaplayici.com/mcp/math |
| Tax | https://hesaplayici.com/mcp/tax |
| Time | https://hesaplayici.com/mcp/time |
| Unit Converter | https://hesaplayici.com/mcp/units |
Tools of the gateway: search_tools, get_tool, run_tool
Claude Code
Run in a terminal:
claude mcp add --transport http hesaplayici https://hesaplayici.com/mcpclaude.ai
Settings › Connectors › Add custom connector; enter this URL:
https://hesaplayici.com/mcpClaude Desktop (claude_desktop_config.json)
Add it to the config file; the mcp-remote bridge connects to the server over HTTP:
{
"mcpServers": {
"hesaplayici": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://hesaplayici.com/mcp"
]
}
}
}Cursor (.cursor/mcp.json)
Add it to the file in your project folder:
{
"mcpServers": {
"hesaplayici": {
"url": "https://hesaplayici.com/mcp"
}
}
}VS Code (.vscode/mcp.json)
Add it to the file in your project folder:
{
"servers": {
"hesaplayici": {
"type": "http",
"url": "https://hesaplayici.com/mcp"
}
}
}ChatGPT
Turn on developer mode in the settings and create a connector with this URL; authentication: none.
https://hesaplayici.com/mcpMCP Inspector
Try it with the MCP Inspector:
npx -y @modelcontextprotocol/inspector --cli https://hesaplayici.com/mcp --transport http --method tools/listTool reference
The input fields, limits, defaults and outputs of every tool are generated from the tool definition, so each tool’s reference page matches the code in every build. Open a tool’s page from the list below.