PoliErgaleio Public Calculation API & MCP Server

Free MCP server and REST API for Cyprus income tax, state pension, retirement stress test and unemployment benefit calculations. Setup guides for Claude Desktop, ChatGPT, Gemini and Cursor.

Endpoints

Authentication

Anonymous-first: omit x-api-key to try instantly (10/min, 50/day, 200/week on stateless calculators). Get a free key at https://poliergaleio.com/profile for 60/min, 1,000/day, 5,000/week plus saved-calculation tools. Send x-guest-id (any opaque id) to avoid sharing anonymous quota. Always prefer structuredContent over content text.

ChatGPT Work MCP plugin: connect https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp. The six saved-calculation tools request PoliErgaleio OAuth sign-in; calculators remain anonymous. Register the exact callback URL shown by ChatGPT as a confidential client in Supabase Authentication → OAuth Apps, then enter that client's ID and secret in the plugin settings.

Calculator inputs (API 3.0.1)

REST and MCP share strict request validation. Reuse facts already provided and ask only for missing essential inputs; request personal facts from the user instead of copying schema examples, which are examples and never defaults. Missing or invalid fields return actionable fieldErrors and hint rather than an estimate. Successful results include structuredContent.assumptions and a concise text disclosure for defaults and exclusions actually used. API 3.0.1 clarifies that rent-vs-buy must ask for the unit of a deposit such as “20” before interpreting it or calculating, and stock-option gain, tax and savings figures require user-confirmed scheme approval before any personalized calculation. It retains API 2.0.1 guidance to confirm financial facts remembered from another chat or scenario and disclose material assumptions and excluded costs; mortgage simulation is reserved for repayment and rate scenarios.

API keys: limits, scopes, headers, rotation, errors

• Limits: at most 10 active keys per account; creation capped at 3 new keys per 24h. Keyed quota is enforced per key and account-wide (revoked keys included).
• Scopes: every key carries scopes ["read", "write"]. Stateless calculators work anonymously; list/load/save/update/delete/compare of saved calculations require a key scoped to its own account.
• Headers: send x-api-key: YOUR_KEY on every request (never in URLs or client bundles). Optional x-guest-id separates anonymous quota; optional X-Request-Id is echoed back for support.
• Rotation: create a new key at https://poliergaleio.com/profile, switch your app, then revoke the old one (immediate). The full secret shows once — copy it then; only the prefix is stored.
• Errors: 400 validation (fieldErrors + hint, check GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/schemas/<tool_name>), 401 missing/invalid key (verify at https://poliergaleio.com/developers/verify), 404 unknown tool/save, 429 rate limit (Retry-After; scope "account" means new keys will not help). Removed tools return 410, stale clients 426 (shared lifecycle error schema).

All developer platforms use the same API

MCP host? Use https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp. ChatGPT Actions? Use https://poliergaleio.com/poliergaleio-chatgpt-actions.json (Action 1, 19 calculators) plus optionally https://poliergaleio.com/poliergaleio-chatgpt-user-actions.json (Action 2, 6 saved-calculation tools). Full OpenAPI import (Copilot, Poe)? Use https://poliergaleio.com/poliergaleio-openapi.json (32 operations — exceeds ChatGPT's 30-operation limit). Grok / Gemini / anything else? POST https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/tools/<tool_name> with the schema from GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/schemas/<tool_name> (examples[0] is ready to send). Never re-implement Cyprus rules.

Claude Desktop / Claude Code (MCP)

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json). Anonymous-first: delete the "--header" lines to try without a key, then restart Claude Desktop:

{
  "mcpServers": {
    "poliergaleio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp",
        "--header",
        "x-api-key:YOUR_API_KEY"
      ]
    }
  }
}

Claude Code: claude mcp add --transport http poliergaleio https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp --header "x-api-key: YOUR_API_KEY" (omit --header for anonymous).

Cursor (MCP)

{
  "mcpServers": {
    "poliergaleio": {
      "url": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Anonymous-first: omit "headers" entirely to try without a key.

ChatGPT (Actions / MCP)

Use https://poliergaleio.com/poliergaleio-chatgpt-actions.json (Action 1, 19 calculators, Authentication: None) as the Action schema, plus optionally https://poliergaleio.com/poliergaleio-chatgpt-user-actions.json (Action 2, saved calculations, Authentication: OAuth). Full https://poliergaleio.com/poliergaleio-openapi.json (32 operations) is for Copilot/Poe/REST only and will not import into ChatGPT. Privacy Policy URL (required to publish): https://poliergaleio.com/privacy.

Gemini (REST / function calling) + Grok / any other assistant

Call any tool with plain HTTP POST. Gems have no tools — use AI Studio / Vertex AI with a FunctionDeclaration, then execute REST yourself. Grok API is OpenAI-compatible: same function JSON works. Example:

curl -s -X POST https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/tools/calculate_cyprus_income_tax \
  -H "Content-Type: application/json" \
  -d '{"salaryIncome": 45000, "legislationVersion": "2026", "employmentType": "private"}'
# Anonymous-first: omit x-api-key to try. Keyed: add -H "x-api-key: YOUR_API_KEY". Schemas: GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/schemas/{tool_name}

Available tools

🔑 requires an API key; all other tools work anonymously at the lower rate limits.

Use it on your phone

Remote MCP servers work inside desktop apps. On mobile or the web, use a ChatGPT Custom GPT or Claude's custom connectors instead.

ChatGPT (Custom GPT)

The easiest way for normal users. The GPT calls PoliErgaleio through two size-limited Actions (the full OpenAPI spec has 32 operations and exceeds ChatGPT's 30-operation limit).

• Open ChatGPT → Explore GPTs → Create.
• Turn on Actions, Action 1: import from URL https://poliergaleio.com/poliergaleio-chatgpt-actions.json (19 calculators).
• Set Action 1 Authentication to None (anonymous tier). Optional Action 2: import https://poliergaleio.com/poliergaleio-chatgpt-user-actions.json with OAuth sign-in for saved calculations.
• Publish as "Anyone with the link" and share.

GPT instructions (copy-paste):

You are a Cyprus financial calculator assistant powered by PoliErgaleio. Use the available tools to answer questions about Cyprus income tax, state pension, retirement stress tests, unemployment benefit, capital gains, mortgages, rent vs buy, stock options, EV savings, budgeting, portfolio performance and life-insurance surrenders. Always ask for missing required inputs. Mention that results use current Cyprus tax rules (2025/2026) and are estimates, not tax advice.

Claude (custom connector)

Claude supports remote MCP custom connectors on Free, Pro, Max, Team and Enterprise plans (Free users get one connector). Works on iOS, Android and the web.

1. Open claude.ai or the Claude app.
2. Go to Settings → Connectors → Add custom connector.
3. Paste the MCP endpoint URL: https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp.
4. Add a custom header: x-api-key with your API key, or leave it out for anonymous use.
5. Enable the connector in a new chat and ask your question.

Is this server legitimate?

• Operated by: PoliErgaleio (poliergaleio.com)
• Hosted on: Supabase Edge Functions tied to this project.
• What the server sees: Only the JSON payload you send. API keys are used for rate-limiting and owner-scoped saved-calculation lookups.
• What it cannot see: Your PoliErgaleio web session, saved-calculation encryption keys, or third-party accounts. Encrypted saves stay locked (locked: true) and are never decrypted through the API — open password-protected saves on poliergaleio.com instead.
• Verify yourself: discovery manifest /.well-known/mcp.json, tool list GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/tools, key check GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/whoami, browser checker /developers/verify, OpenAPI /poliergaleio-openapi.json.

Staying up to date

• Every response carries the current API version in the X-API-Version header and the apiVersion body field. Check GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/version for the current version and changelog.
• MCP clients (Claude, Cursor) pick up new tools automatically on reconnect — no reinstall needed.
• ChatGPT Custom GPTs cache the Action schema; re-import /poliergaleio-chatgpt-actions.json (and /poliergaleio-chatgpt-user-actions.json if used) in the GPT editor to pick up new tools.
• Breaking changes are announced in advance with Deprecation and Sunset headers plus a plain-language notice field in the response body.
• GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/migrations/latest returns the newest migration guide with #what-changed, #tool-changes and #update-steps deep links. It is cacheable: keep the ETag and send If-None-Match to get a 304 (Cache-Control: public, max-age=300, stale-while-revalidate=86400).
• Validate lifecycle errors automatically against the published JSON Schema 2020-12: /poliergaleio-lifecycle-error.schema.json (also live at GET https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/schemas/errors/lifecycle). It covers both 410 Gone (code: "tool_gone") and 426 Upgrade Required (code: "upgrade_required"), which share error, code, tool, status, replacement, migrationGuide and migrationSections.

Copy-paste examples

# Newest migration guide, keeping the ETag for later revalidation
curl -sD - https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/migrations/latest -o latest.json | grep -i -E '^(etag|cache-control)'

# Revalidate: 304 with an empty body while the guide is unchanged
curl -s -o /dev/null -w '%{http_code}
' -H 'If-None-Match: "<stored-etag>"'   https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/migrations/latest

# Validate an error body against the published schema
curl -s https://poliergaleio.com/poliergaleio-lifecycle-error.schema.json -o lifecycle-error.schema.json
npx ajv-cli validate -s lifecycle-error.schema.json -d error-body.json --spec=draft2020

# 426 Upgrade Required (stale client)
curl -s -X POST https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/tools/calculate_cyprus_income_tax   -H 'Content-Type: application/json' -H 'X-Client-Version: 0.9.0'   -d '{"salaryIncome": 45000}'

Downloads

• Postman collection
• Postman environment
• OpenAPI 3.1 spec (full, 32 ops)
• ChatGPT Calculators Action (19 tools)
• ChatGPT User Saves Action (6 tools)
• Plain-text developer reference