# MFOXA — Ukraine Microfinance Catalog (MCP Server)

Public **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for the catalog of licensed Ukrainian microfinance organizations (MFOs), powered by [mfoxa.com.ua](https://mfoxa.com.ua) — МФОХА, a Ukrainian MFO comparison marketplace.

| | |
|---|---|
| **Endpoint** | `https://mfoxa.com.ua/api/mcp` |
| **Transport** | Streamable HTTP (stateless) |
| **Authentication** | none (public data) |
| **Registry** | [`ua.com.mfoxa/catalog`](https://registry.modelcontextprotocol.io/v0/servers?search=mfoxa) (official MCP Registry, domain-verified) |
| **Server card** | [`/.well-known/mcp/server-card.json`](https://mfoxa.com.ua/.well-known/mcp/server-card.json) |
| **Languages** | Ukrainian (`uk`, default) and Russian (`ru`) via the `lang` parameter |
| **Rate limit** | 60 requests/min per IP → HTTP 429 |

Every entity in every response carries a `canonical_url` pointing to the live page on mfoxa.com.ua.

## Tools

| Tool | Parameters | Returns |
|---|---|---|
| `list_mfo` | `lang?` | All MFOs with borrower rating and canonical card URLs. `rating: null` means *no reviews yet*, not a low score. |
| `get_mfo` | `slug`, `lang?` | Full MFO card: terms for new/repeat clients (amount, term, rate), effective annual rate, legal entity, NBU license, official disclosure PDFs, 4-criteria rating, record update date. |
| `search_offers` | `amount?`, `term_days?`, `first_loan_zero?`, `region?`, `limit?` (default 15), `lang?` | Matching first-loan offers with terms, `first_loan_zero_percent: true/false/null` (null = unconfirmed), honest `total` + `truncated`. `region` (oblast slug from `list_regions`) narrows the search to MFOs lending in that oblast. |
| `list_categories` | `lang?` | Catalog categories in two separate groups — credit (site root) and loan (`/loan/`) — each with its selection criterion. |
| `get_category` | `slug`, `lang?` | One category: criterion, sorting, offer table with per-MFO terms. |
| `get_reviews` | `slug`, `limit?` (≤10), `lang?` | Latest borrower reviews for an MFO: rating, date, text. |
| `get_market_rules` | `lang?` | Legal context of microlending in Ukraine (1%/day rate cap under Law 3498-IX, mandatory creditworthiness assessment, penalty caps, debt collection rules, military credit holidays) with last-review date. Legal facts are maintained in Ukrainian only. |
| `list_regions` | `lang?` | Ukrainian oblasts (plus Kyiv as a city-region) that have "loans in your city" pages: number of cities, number of MFOs lending there, `canonical_url` and `markdown_url`. MFOs are attached per oblast, so the MFO list is the same for every city of one oblast. |
| `get_city` | `region`, `city?`, `lang?` | Without `city`: the oblast page — its cities (slug + `canonical_url`) and the oblast's MFO offer table. With `city`: the city page — same MFOs, `canonical_url` and `markdown_url` of the page with text and FAQ. `region=kyiv` returns the Kyiv city page directly. |

Resources: [`llms.txt`](https://mfoxa.com.ua/llms.txt) and [`llms-full.txt`](https://mfoxa.com.ua/llms-full.txt).

## Installation

### Claude (claude.ai / Claude Desktop)

1. **Settings → Connectors → Add custom connector**
2. Name: `MFOXA catalog`, URL: `https://mfoxa.com.ua/api/mcp`
3. Save. No API keys or OAuth — the server is public and read-only.

### Any MCP client (generic)

Point your client at the remote Streamable HTTP endpoint:

```json
{
  "mcpServers": {
    "mfoxa-catalog": {
      "type": "streamable-http",
      "url": "https://mfoxa.com.ua/api/mcp"
    }
  }
}
```

Quick sanity check with MCP Inspector:

```bash
npx @modelcontextprotocol/inspector --cli https://mfoxa.com.ua/api/mcp --transport http --method tools/list
```

## Example prompts

- *"Find Ukrainian microloans up to 10 000 UAH for two weeks where the first loan is interest-free."*
- *"Show the legal entity, NBU license and current terms for Credit7."*
- *"What are the legal limits on microloan interest rates in Ukraine?"*
- *"List the top-rated Ukrainian MFOs by borrower reviews and link their pages."*
- *"Which MFOs lend online in Lviv? Link the city page."*
- *«Підбери кредит до 10 000 грн на два тижні, у кого перший кредит під 0%»*
- *«Покажи умови та юридичні дані Credit7»*
- *«Де взяти 5000 грн на місяць у Харківській області?»*

## Screenshot

<!-- TODO: replace with a screenshot of a live Claude conversation using the connector -->
*Screenshot of a live Claude dialog coming soon.*

## Data & Terms

- **Public read-only catalog data.** The server exposes the same data that is publicly visible on mfoxa.com.ua. There are no mutation tools.
- **Not financial advice.** МФОХА is a comparison catalog, not a lender. Terms are volatile — final conditions live on the `canonical_url` pages.
- **Attribution required.** When using the data, cite the `canonical_url` of the respective page on mfoxa.com.ua.
- **Rate limit:** 60 requests/min per IP.
- No tracker or affiliate links anywhere in responses (enforced by tests).

## Українською

МФОХА — каталог і рейтинг мікрофінансових організацій України з ліцензією НБУ. Цей MCP-сервер віддає ті самі публічні дані, що й сайт: умови кредитів для нових і повторних клієнтів, реальну річну ставку, юридичні дані та офіційні документи компаній, рейтинг і відгуки позичальників, витрини за областями та містами («кредит онлайн у вашому місті»), правовий контекст мікрокредитування (ліміт ставки 1% на день за Законом 3498-IX тощо). Сервер read-only, без автентифікації; при використанні даних посилайтеся на canonical_url відповідної сторінки.

## Links

- Website: https://mfoxa.com.ua
- Server card: https://mfoxa.com.ua/.well-known/mcp/server-card.json
- llms.txt: https://mfoxa.com.ua/llms.txt
- Contact: admin@mfoxa.com.ua

## License

Documentation in this repository is licensed under [MIT](LICENSE). The catalog data served by the MCP endpoint is proprietary to МФОХА (mfoxa.com.ua) and may be used with attribution to canonical URLs.