Developers

Tested servers. Clear contracts.

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

Claude.ai (custom connector)

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

https://mcp.zovo.one/mcp/currency/t/<token>

Full Claude.ai guide

Claude Desktop (.mcpb bundle)

Open https://mcp.zovo.one/downloads#currency and download currency.mcpb.
Double-click the file. Claude Desktop opens the install dialog.
Click Install. No Node.js, no JSON, no terminal.
Restart Claude Desktop if the tools don't appear.

https://github.com/theluckystrike/mcp-servers/releases/download/v0.22.0/currency.mcpb

Full Claude Desktop guide

Claude Desktop (JSON config)

Install Node.js 18 or newer.
Open claude_desktop_config.json. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json.
Merge the entry below into the mcpServers object. Don't overwrite other entries.
Quit and restart Claude Desktop.
For the hosted server, don't use this file: use Settings, then Connectors, and paste the URL as for Claude.ai.

{
  "mcpServers": {
    "currency": {
      "command": "npx",
      "args": [
        "-y",
        "@theluckystrike/mcp-currency"
      ]
    }
  }
}

Full Claude Desktop guide

Claude Code (claude mcp add, hosted)

Get a token: curl -s -X POST https://mcp.zovo.one/mcp/token
Run the command below. Replace <token>.
Run claude mcp list to confirm the server is connected.

claude mcp add --transport http currency https://mcp.zovo.one/mcp/currency --header "Authorization: Bearer <token>"

Full Claude Code guide

Claude Code (claude mcp add, local)

Install Node.js 18 or newer.
Run the command below.
Run claude mcp list to confirm.

claude mcp add currency -- npx -y @theluckystrike/mcp-currency

Full Claude Code guide

Cursor

Open ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
Merge the entry below. Replace <token>.
Open Cursor Settings, then MCP, and check that the server shows its tools.

{
  "mcpServers": {
    "currency": {
      "url": "https://mcp.zovo.one/mcp/currency/t/<token>"
    }
  }
}

Full Cursor guide

VS Code

Create .vscode/mcp.json in your workspace. The top key is servers, not mcpServers.
Paste the entry below. Replace <token>.
Open the Chat view in Agent mode and start the server from the tools list.

{
  "servers": {
    "currency": {
      "type": "http",
      "url": "https://mcp.zovo.one/mcp/currency/t/<token>"
    }
  }
}

Full VS Code guide

Windsurf

Open ~/.codeium/windsurf/mcp_config.json.
Merge the entry below. Replace <token>.
Refresh the MCP servers list in Cascade.

{
  "mcpServers": {
    "currency": {
      "serverUrl": "https://mcp.zovo.one/mcp/currency/t/<token>"
    }
  }
}

Full Windsurf guide

ChatGPT

Status: unknown. Not tested.
ChatGPT accepts remote MCP servers only in developer mode on some plans.
The server publishes OAuth discovery documents (/.well-known/oauth-protected-resource returns 200), so the URL form may work. This isn't verified.

https://mcp.zovo.one/mcp/currency/t/<token>

Full ChatGPT guide

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).

Code	Meaning	Fix
HTTP 401 unauthorized	tools/call on the bare URL with no token.	Use /mcp/<server>/t/<token> or send Authorization: Bearer <token>.
HTTP 401 unknown_token	Token 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_token	Token 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_found	Unknown server id in the URL.	Check the id against GET https://mcp.zovo.one/mcp (endpoints list).
HTTP 406 Not Acceptable	A 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 -32602	HTTP 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

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).
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.
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.
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.
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.
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.
Every server registers license_status and license_activate. Call license_status first to prove the transport works.

Conventions

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.

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.

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.

Logging

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

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.

Tests

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

Stack

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

Developer FAQ

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. Buying Pro funds the maintenance.

Get the bundle