MCP IntegrationNovember 10, 2026 / 9 min read

Currency Data for AI Agents: MCP Integration Guide (2026)

AI agents keep reimplementing the same glue: a function schema per provider, an HTTP handler, a retry loop. The Model Context Protocol replaces that glue with one server URL. This guide connects payroll agents, expense bots, and pricing assistants to live and historical FX data through the Currency-Exchange.app MCP server.

Currency-Exchange.app hosts a read-only MCP server at https://api.currency-exchange.app/mcp. It speaks Streamable HTTP — plain JSON-RPC 2.0 POSTs with the Accept: application/json, text/event-stream header — and authenticates with the same API key as the REST API. In development the endpoint resolves to NEXT_PUBLIC_API_URL_MODULE_APP plus /mcp.

The payoff is provider neutrality. One server configuration serves Claude, GPT, Gemini, and open-source clients that support Streamable HTTP. Swap the model, keep the currency tools, the auth, and the billing contract untouched.

Where agents actually need currency data

Payroll agents

A payroll copilot converts contractor invoices into the reporting currency using invoice-date rates, stores rateTime as evidence, and flags pairs that moved more than the policy tolerance before the payment run.

Expense bots

An expense assistant reads a receipt in JPY, converts it with the receipt-date rate, and writes the local amount plus the rate used straight into the report line — no spreadsheet lookups by the employee.

Marketplace pricing agents

A pricing agent refreshes seller price books in local currencies, validates ISO codes against the currency catalog, and quotes buyers with the live rate and its timestamp attached.

Client setup in one block

Create an API key under Account → API keys, then register the server in any MCP-capable client. Keys are host-scoped: a Currency-Exchange key authorizes exactly the currency tools on this host and nothing else.

{
  "mcpServers": {
    "currency-exchange": {
      "type": "http",
      "url": "https://api.currency-exchange.app/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Prefer to evaluate before wiring a client? The Scalar reference on /open-api ships an MCP panel that connects in one click, and discovery metadata is published at /llms.txt and /.well-known/mcp/server-card.json.

Tool walkthroughs with real JSON-RPC traffic

Every session starts with the initialize handshake. The response embeds agent instructions — how to authenticate, what a call costs, and what a 402 means — so the model learns the contract from the server itself.

curl -X POST https://api.currency-exchange.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "payroll-agent", "version": "1.0.0" }
    }
  }'

The initialize result (abbreviated):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": { "name": "any-xyz", "version": "1.0.0" },
    "instructions": "Authentication: - Send your API key in the \"x-api-key\" header ... Billing and usage: - Every successful tool call consumes 1 credit ... except account_whoami which is free."
  }
}

An expense bot turns a Tokyo dinner receipt into the reporting currency using the receipt-date rate. The inverse rate comes back in the same payload, so the agent never divides by hand:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "currency_get_rate",
    "arguments": { "from": "JPY", "to": "USD", "date": "2026-11-05" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{\"from\":\"JPY\",\"to\":\"USD\",...}" }],
    "structuredContent": {
      "from": "JPY",
      "to": "USD",
      "exchangeRate": 0.0065,
      "rateTime": "2026-11-05T00:00:00.000Z",
      "inverseRate": 153.85,
      "disclaimer": ""
    }
  }
}

A conversion applies the rate to an amount and returns both machine fields and a human-readable line the agent can quote directly:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "currency_convert",
    "arguments": { "amount": 250, "from": "USD", "to": "EUR" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "from": "USD",
      "to": "EUR",
      "exchangeRate": 0.9125,
      "rateTime": "2026-11-10T09:41:23.000Z",
      "originalAmount": 250,
      "convertedAmount": 228.125,
      "convertedText": "250 USD equal to 228.13 EUR"
    }
  }
}

Tool reference

Tool	Returns	Key arguments
account_whoami	User id, email, and username behind the API key. Free.	none
currency_list	Paginated fiat catalog: codes, names, symbols, locales.	codes, search, page, pageSize
currency_get_rate	Live or historical rate for a pair plus the inverse rate.	from, to, date?
currency_convert	Converted amount, rate, rateTime, and a readable text line.	amount?, from, to, date?

All tools are read-only and idempotent. Historical lookups pass a date argument (YYYY-MM-DD); omit it for the latest rate.

An agent workflow, end to end

A payroll agent processing a foreign contractor invoice runs the same five steps every month. Only steps 2-4 cost credits.

1. Verify the connection (free)

The agent calls account_whoami to confirm the key works and report remaining credits before any billable call.

2. Validate the currency codes

currency_list with search or codes confirms the ISO 4217 codes the user mentioned are supported before credits are spent.

3. Pull the rate with evidence

currency_get_rate (with date for invoice or receipt dates) returns the rate, rateTime, and inverseRate; the agent stores them with the workflow record.

4. Convert the amount

currency_convert applies the rate to the amount and returns convertedAmount plus convertedText for the user-facing answer.

5. Handle billing states

A 402 response pauses the workflow and points the user at the pricing page; the agent resumes once credits are topped up.

Billing, credits, and error states

One credit per tool call

Every successful call consumes one credit from the API key owner and lands in daily usage and billing. The free identity probe keeps agents honest — this call costs nothing and reports the account behind the key:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "account_whoami",
    "arguments": {}
  }
}

HTTP 402 means out of credits

When the account runs dry, the server answers 402 PAYMENT_REQUIRED before the tool runs. The intended agent behavior is in the initialize instructions: tell the user to top up at /pricing, then retry. A 401, by contrast, means the key is missing, invalid, or scoped to another host — retrying never helps.

Internal links for the implementation path

FAQ

What is the Currency-Exchange.app MCP endpoint?

The hosted MCP server lives at https://api.currency-exchange.app/mcp. It speaks Streamable HTTP: clients POST JSON-RPC 2.0 messages with the Accept: application/json, text/event-stream header. In development the same surface is reached at NEXT_PUBLIC_API_URL_MODULE_APP with the /mcp path appended.

How do AI agents authenticate to the MCP server?

Agents send a Currency-Exchange API key in the x-api-key header, created under Account → API keys. Keys are host-scoped, so keys from other products are rejected. A demo key (demo-key plus a valid TOTP in the x-ct header) gives limited trial access.

How much does an MCP tool call cost?

Every successful tool call consumes one credit from the API key owner. account_whoami is free and also reports remaining credits. When the account runs out, the server returns HTTP 402 PAYMENT_REQUIRED before the tool runs, and the initialize instructions tell agents to send the user to the pricing page.

Which currency tools does the MCP server expose?

Four read-only tools: account_whoami (free identity probe), currency_list (paginated fiat catalog with search), currency_get_rate (live and historical rates plus the inverse), and currency_convert (amount conversion with rate detail). All carry readOnlyHint and idempotentHint annotations.

Do agents need custom code per LLM provider?

No. MCP is the provider-neutral layer: the same server config works for Claude, GPT, Gemini, and open-source clients that support Streamable HTTP. Provider-native function calling is still useful when you want hand-tuned schemas — the HTTP tool calling article covers that path.

Give your agents live currency data this week

One endpoint, four tools, one credit per call. Create an API key, paste the server URL into your MCP client, and let the initialize instructions teach the rest to your agent.

Read the MCP guide Open the API reference