Tools Reference

This page documents the five MCP tools exposed by the Kurslog connector. All tools are read-only (readOnlyHint: true). Responses are JSON, capped well under MCP's 25 000-token result limit.

Common arguments

Argument	Type	Description
`locale`	"uk" \| "ru" \| "en"	Response language. Default `uk`.
`from_currency`	string ≤ 40 chars	Source currency slug (e.g. `usdt-trc20`).
`to_currency`	string ≤ 40 chars	Target currency slug (e.g. `monobank-uah`, `cash-uah`).
`city`	string ≤ 50 chars	Optional city slug (e.g. `kyiv`) for cash directions.

`list_currencies`

Purpose: discover currency codes used by all other tools.

Cache TTL: 3600 s.

Arguments:

{
  "locale": "en",
  "only_with_rates": true,    // default true
  "limit": 200                // 1..300, default 200
}

Example response (truncated):

{
  "count": 200,
  "locale": "en",
  "currencies": [
    {"code": "usdt-trc20", "name": "USDT TRC20", "asset": "USDT",
     "popularity": 1, "tags": ["USDT"], "has_rates": true},
    {"code": "bitcoin", "name": "Bitcoin", "asset": "BTC",
     "popularity": 2, "tags": ["Crypto"], "has_rates": true}
  ]
}

`find_best_rate`

Purpose: top 3 best offers for a currency pair, with optional city for cash directions.

Cache TTL: 60 s.

Arguments:

{
  "from_currency": "usdt-trc20",
  "to_currency": "cash-uah",
  "city": "kyiv",          // optional
  "locale": "en"
}

Example response:

{
  "direction": {"from": "usdt-trc20", "to": "cash-uah", "city": "kyiv"},
  "best_offers": [
    {
      "exchanger_name": "Dvizh",
      "exchanger_slug": "dvizh",
      "exchanger_rating": 5.0,
      "trust_status": "Diamond",
      "rate_in": 1,
      "rate_out": 44.13,
      "reserves": 170916400.39,
      "min_amount": 566.45,
      "max_amount": 2000000,
      "kurslog_link": "https://kurslog.com/usdt-trc20-to-cash-uah-in-kyiv"
    }
    // ... up to 3 entries
  ],
  "disclaimer": "Rates may be stale up to 5 minutes..."
}

Empty result: if no exchangers match (invalid pair, wrong city slug), returns a structured success with results: [] and an explanatory message — never an exception.

`compare_exchangers`

Purpose: broader list (up to 20) with trust score, reserves, profile links.

Cache TTL: 60 s.

Arguments:

{
  "from_currency": "bitcoin",
  "to_currency": "monobank-uah",
  "limit": 10,             // 1..20, default 10
  "city": null,            // optional
  "locale": "en"
}

Same response shape as find_best_rate, except exchangers array of up to limit items, each enriched with trust_score (numeric) and profile_link.

`get_exchanger_profile`

Purpose: single exchanger's profile — trust, contacts, founding date.

Cache TTL: 600 s.

Arguments:

{
  "exchanger_slug": "digichanger",
  "locale": "en"
}

Example response:

{
  "name": "Digichanger",
  "slug": "digichanger",
  "status": "active",
  "founding_date": "2023-05-19",
  "website": "https://www.digichanger.pro",
  "trust": {
    "label": "Diamond",
    "name": "diamond",
    "explanation": "Reviews: 3338 across 4 monitoring platforms. On the market: 3 years.",
    "domain_age_years": 3.01
  },
  "kurslog_profile": "https://kurslog.com/exchanger/digichanger"
}

`find_cities_for_direction`

Purpose: Ukrainian (and nearby) cities where a cash exchange direction is currently active.

Cache TTL: 3600 s.

Arguments:

{
  "from_currency": "usdt-trc20",
  "to_currency": "cash-eur",
  "limit": 15,             // 1..30, default 15
  "locale": "en"
}

Example response (truncated):

{
  "direction": {"from": "usdt-trc20", "to": "cash-eur"},
  "count": 15,
  "cities": [
    {"city": "Kyiv", "slug": "kyiv", "exchanger_count": 16,
     "best_rate": 0.0234, "kurslog_link": "https://kurslog.com/usdt-trc20-to-cash-eur-in-kyiv"}
    // ...
  ]
}

Error handling

Every tool follows the MCP convention. Failed upstream requests or unknown slugs do not raise an MCP isError: true. Instead they return a structured empty result with a human-readable message field explaining what to try next. This lets Claude give the user a useful answer rather than a stack trace.

Rate limits

The connector applies a 60 req/min/IP limit at the nginx layer. Combined with per-tool caching, you should never hit it through normal Claude usage. If you do, you'll get a 429 from the HTTP layer.