Skip to content
MCPSTAMP
Developers

Clear tool contracts. Two ways to run.

Each server is a small TypeScript or JavaScript program that speaks MCP. It runs on your machine over stdio, or on a hosted endpoint over streamable HTTP. The tool contract is the same on both paths.

Quickstart Hosted endpoints Tool contracts GitHub

Quickstart

  1. 01

    Claude.ai (custom connector)

    1. Open https://mcp.zovo.one/mcp/connect and copy the ready URL for your server. It already contains a free token.
    2. In Claude.ai, open Settings, then Connectors, then Add custom connector.
    3. Paste the URL. Leave the OAuth fields empty. Save.
    4. Start a new chat and ask: Convert 100 EUR to USD.
    Full Claude.ai guide 
    https://mcp.zovo.one/mcp/currency/t/<token>

  2. 02

    Claude Desktop (.mcpb bundle)

    1. Open https://mcp.zovo.one/downloads#currency and download currency.mcpb.
    2. Double-click the file. Claude Desktop opens the install dialog.
    3. Click Install. No Node.js, no JSON, no terminal.
    4. Restart Claude Desktop if the tools don't appear.
    Full Claude Desktop guide 
    https://github.com/theluckystrike/mcp-servers/releases/download/v0.22.0/currency.mcpb

  3. 03

    Claude Desktop (JSON config)

    1. Install Node.js 18 or newer.
    2. Open claude_desktop_config.json. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json.
    3. Merge the entry below into the mcpServers object. Don't overwrite other entries.
    4. Quit and restart Claude Desktop.
    5. For the hosted server, don't use this file: use Settings, then Connectors, and paste the URL as for Claude.ai.
    Full Claude Desktop guide 
    {
  "mcpServers": {
    "currency": {
      "command": "npx",
      "args": [
        "-y",
        "@theluckystrike/mcp-currency"
      ]
    }
  }
}

  4. 04

    Claude Code (claude mcp add, hosted)

    1. Get a token: curl -s -X POST https://mcp.zovo.one/mcp/token
    2. Run the command below. Replace <token>.
    3. Run claude mcp list to confirm the server is connected.
    Full Claude Code guide 
    claude mcp add --transport http currency https://mcp.zovo.one/mcp/currency --header "Authorization: Bearer <token>"

  5. 05

    Claude Code (claude mcp add, local)

    1. Install Node.js 18 or newer.
    2. Run the command below.
    3. Run claude mcp list to confirm.
    Full Claude Code guide 
    claude mcp add currency -- npx -y @theluckystrike/mcp-currency

  6. 06

    Cursor

    1. Open ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
    2. Merge the entry below. Replace <token>.
    3. Open Cursor Settings, then MCP, and check that the server shows its tools.
    Full Cursor guide 
    {
  "mcpServers": {
    "currency": {
      "url": "https://mcp.zovo.one/mcp/currency/t/<token>"
    }
  }
}

  7. 07

    VS Code

    1. Create .vscode/mcp.json in your workspace. The top key is servers, not mcpServers.
    2. Paste the entry below. Replace <token>.
    3. Open the Chat view in Agent mode and start the server from the tools list.
    Full VS Code guide 
    {
  "servers": {
    "currency": {
      "type": "http",
      "url": "https://mcp.zovo.one/mcp/currency/t/<token>"
    }
  }
}

  8. 08

    Windsurf

    1. Open ~/.codeium/windsurf/mcp_config.json.
    2. Merge the entry below. Replace <token>.
    3. Refresh the MCP servers list in Cascade.
    Full Windsurf guide 
    {
  "mcpServers": {
    "currency": {
      "serverUrl": "https://mcp.zovo.one/mcp/currency/t/<token>"
    }
  }
}

  9. 09

    ChatGPT

    1. Status: unknown. Not tested.
    2. ChatGPT accepts remote MCP servers only in developer mode on some plans.
    3. The server publishes OAuth discovery documents (/.well-known/oauth-protected-resource returns 200), so the URL form may work. This isn't verified.
    Full ChatGPT guide 
    https://mcp.zovo.one/mcp/currency/t/<token>

Hosted endpoint

Free token

curl -s -X POST https://mcp.zovo.one/mcp/token

GET works too. Or open https://mcp.zovo.one/mcp/connect in a browser for ready URLs.

URL forms

  • https://mcp.zovo.one/mcp/<server>/t/<token>

    path: Clients that accept only a URL (Claude.ai, Cursor, VS Code, Windsurf).

  • https://mcp.zovo.one/mcp/<server>Authorization: Bearer <token>

    header: Clients that can set headers (Claude Code, SDKs, curl). The header wins over a token in the URL.

  • https://mcp.zovo.one/mcp/<server>?token=<token>

    query: Clients that take a query string but no header.

  • https://mcp.zovo.one/mcp/<server>

    bare: Answers initialize and tools/list. Refuses every tools/call with 401. Not a working install.

Limits

calls free
600 per hour per token (counter resets at the top of the UTC hour)
calls pro
6000 per hour
token mints
10 per hour per IP. Reuse your token.
token life
30 days, refreshed on every write
data retention
30 days on free. Idle data swept after 35 days
request body
256 KB per request (base64 files: about 190 KB)
stored per token per server
512 KB default. 2 MB for spreadsheet, docx, resume, pdf, calendar, image, bank-statement, zip, cash-book
server free limits
Each server keeps its own free-tier limits (example: invoice_create 3 per month).
CodeMeaningFix
HTTP 401 unauthorizedtools/call on the bare URL with no token.Use /mcp/<server>/t/<token> or send Authorization: Bearer <token>.
HTTP 401 unknown_tokenToken has the right form but the server doesn't know it (expired, mistyped, or never minted).Mint a new token: curl -s -X POST https://mcp.zovo.one/mcp/token
HTTP 401 invalid_tokenToken is neither anon_<32 hex> nor an MCPL1 Pro key.Copy the whole token. Check for spaces or a missing prefix.
HTTP 429 rate_limited (calls)The token made 600 calls this hour. Body has resets_at and retry_after_seconds.Wait for resets_at, or buy Pro (6000 per hour). Clients that re-handshake every turn spend calls before any tool runs.
HTTP 429 rate_limited (mint)Your IP minted 10 tokens this hour.Reuse the token you have. One token is one data space.
HTTP 404 not_foundUnknown server id in the URL.Check the id against GET https://mcp.zovo.one/mcp (endpoints list).
HTTP 406 Not AcceptableA GET without Accept: text/event-stream (for example, opening the URL in a browser).Send POST with a JSON-RPC body. A browser can't test the URL.
HTTP 405 method_not_allowed/mcp/token called with a method other than GET or POST.Use POST or GET.
isError: MCP error -32602HTTP 200, but the tool name or arguments are wrong. Example: Tool nope not found.Call tools/list and use an exact tool name and the inputSchema.

Architecture

  1. On the local stdio path, your MCP client starts node dist/index.js. Nothing leaves your machine except calls the tool itself needs (example: currency fetches ECB rates).

  2. The local install keeps JSON files under ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/<server>/. Writes are atomic (temp file + rename). Delete the folder to reset a server.

  3. business_set writes one shared business profile to ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json. Invoice, quotes, credit notes and the other document servers read it, so you set your name, address, VAT id and defaults once.

  4. The Pro key is read from MCP_LICENSE_KEY, then ${XDG_CONFIG_HOME:-~/.config}/mcp-servers/license.json, then the free tier applies. Keys (MCPL1.<payload>.<signature>) are checked offline with Ed25519. No phone-home.

  5. On the hosted path (streamable HTTP), 46 of 58 servers run on a Cloudflare Worker at https://mcp.zovo.one/mcp/<server>. Data is stored per token, kept 30 days, and file tools take inline uploads and return download URLs that expire.

  6. Four servers are local only: office-suite, three-way-match, duplicate-invoice-check and supplier-statement-check have no hosted URL. Use the .mcpb bundle, npm or a source build.

  7. Every server registers license_status and license_activate. Call license_status first to prove the transport works.

Conventions

  1. Tool results

    Success: {content:[{type:"text",text}]}. Failure: the same shape with isError: true and text that starts with Error:. Servers don't throw across the transport.

  2. Money in minor units

    Many servers store and return amounts as integer minor units (cents). Some inputs, such as invoice unit_price, take major units. Each tool description says which.

  3. Free tier inside the tool

    A free-tier limit is a normal tool result that names the limit and the upgrade URL. It isn't a protocol error.

  4. Logging

    Servers log to stderr only. stdout carries only protocol messages. One readiness line goes to stderr at start.

  5. Contracts are generated

    Each server has SPEC.md, generated from the built server by scripts/gen-spec.mjs: every tool, every argument, type and required flag.

  6. Tests

    Each server has test/smoke.test.mjs. It spawns dist/index.js and runs initialize, tools/list and one tools/call over stdio.

  7. Stack

    TypeScript, ESM, Node 18 or newer, @modelcontextprotocol/sdk and zod. No native dependencies, so npx works on every platform. MIT license.

Common developer questions

Is the npm package published?
Yes. npm view @theluckystrike/mcp-currency returns 0.22.6 (checked 2026-10-30). Some older pages and llms-install.md files still say it isn't published. They are out of date.
Why does my hosted URL list tools but every call fails?
You used the bare URL. It answers initialize and tools/list, and returns 401 on tools/call. Add the token: /mcp/<server>/t/<token>, or send Authorization: Bearer <token>.
Is the URL with the token a secret?
Yes. The token in the URL is the credential and your data space. Don't share it or commit it.
Can I test the hosted URL in a browser?
No. A browser GET returns 406. Use curl with POST and a JSON-RPC body, as in the example session.
Does the hosted endpoint support OAuth?
The server publishes OAuth discovery documents and an authorize endpoint. The /mcp index says it has no OAuth flow. Use the token forms. They are tested.
Where is my data?
On the local install, in ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/<server>/. On the hosted path, on the server per token for 30 days, refreshed on every write.
How do I move from free to Pro?
Buy at https://mcp.zovo.one/buy/<server> ($19) or /buy/bundle ($39). Then set MCP_LICENSE_KEY or call license_activate once. On hosted, the Pro key can be sent as the token.

Open source, MIT. Pro keys are Ed25519-signed and verify offline, and buying Pro pays for the maintenance.

Get the bundle

Links