MCP Server Guide

What is MCP?

Endpoint, transport, and authentication

Connect an MCP client

Any client that speaks Streamable HTTP works — Claude Desktop and Claude Code, Cursor, VS Code MCP extensions, or the reference TypeScript and Python SDKs. Add the server to your client configuration:

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

The client must send Accept: application/json, text/event-stream on every POST — that is required by the Streamable HTTP transport. Your API key travels in the x-api-key header and is never part of the URL.

JSON-RPC walkthrough with curl

Start with the initialize handshake. The response carries the protocol version, server info, and agent instructions that document authentication and billing in the result itself.

curl -X POST https://currency-exchange.app/api/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": "curl", "version": "1.0.0" }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": { "name": "any-xyz", "version": "1.0.0" },
    "instructions": "Billing and usage: - Every successful tool call consumes 1 credit ... except account_whoami which is free. - A HTTP 402 PAYMENT_REQUIRED response means the account is out of credits — direct the user to the product pricing page to top up, then retry."
  }
}

Then call a tool. This example converts 250 USD to EUR — every response includes both a machine-readable structuredContent object and a text mirror, so simple clients can render the text line directly.

curl -X POST https://currency-exchange.app/api/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": 2,
    "method": "tools/call",
    "params": {
      "name": "currency_convert",
      "arguments": { "amount": 250, "from": "USD", "to": "EUR" }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"from\":\"USD\",\"to\":\"EUR\",\"exchangeRate\":0.9125,...}"
      }
    ],
    "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

Four read-only tools are exposed on this host. All of them declare readOnlyHint and idempotentHint, so agents can retry safely and providers know nothing here mutates state.

Historical lookups use the date argument (YYYY-MM-DD) on currency_get_rate and currency_convert. Omit it for the latest rate, or pass skipCache when freshness matters more than credits.

Billing and credits

Discovery surfaces

Agent integration checklist