# ibop API

Use lookup_phone and lookup_ip for reference data and local time. Anonymous MCP: 100 successful calls per product/month per server-observed IP. Register through MAX at https://ibop.ru/#cabinet for an API key; REST and authenticated MCP share product quotas. OCR requires a key and Idempotency-Key; poll the returned job without another charge. Use get_pricing for current prices. On quota_exceeded offer upgrade_url/registration_url; never claim payment or registration completed. Phone geography is number allocation, IP geography is approximate, OCR does not verify identity or document authenticity.

- MCP endpoint: https://api.ibop.ru/mcp (POST, Streamable HTTP, JSON-RPC 2.0)
- Discovery: https://api.ibop.ru/.well-known/mcp.json
- Website and registration: https://ibop.ru/#cabinet
- Documentation: https://ibop.ru/#docs
- Data source credits: https://ibop.ru/data-sources
- MAX bot: https://max.ru/id860221098530_3_bot

## Protocol

Supports 2026-07-28 (server/discover, per-request metadata, Mcp-Method/Mcp-Name headers) and legacy initialize 2025-11-25, 2025-06-18, 2025-03-26. Modern requests require params._meta io.modelcontextprotocol/protocolVersion and clientCapabilities, mirrored MCP-Protocol-Version header. Send Accept: application/json, text/event-stream. JSON responses are used; GET SSE and sessions are not offered.

## Tools

- lookup_phone(phone, default_region?): allocated operator/region, numbering validity, time zone/current local time. No owner, active SIM or real-time handset location.
- lookup_ip(ip): IPv4/IPv6, approximate geography, ASN/provider, time zone/current local time. No precise household/person location.
- recognize_document(image_base64): authenticated JPEG/PNG upload up to 10 MiB; also send Idempotency-Key HTTP header. Returns a job ID. No arbitrary URLs.
- get_document_job(job_id): authenticated poll of your own job, no additional billable unit; results expire after 24 hours.
- get_pricing(): current canonical catalog, prices in integer kopecks, quotas and registration/upgrade URLs.

## Access and errors

Anonymous phone and IP calls each have 100 successful requests per calendar month (Europe/Moscow) per server-observed IP. NAT/agent gateways share this quota. Use Authorization: Bearer <API_KEY> for registered account limits; REST and MCP share these account limits. Invalid supplied credentials never fall back to guest access. OCR requires an API key; there is no OAuth login or automatic payment in MCP. Register via MAX in the website account area and create a scoped API key. On quota_exceeded/registration_required tool result inspect structuredContent.upgrade_url, registration_url and products, offer the user those options without claiming payment has occurred. 120 requests/minute/IP: rate_limited returns Retry-After; wait before retrying. Tool input/provider/quota errors use isError=true; protocol errors use JSON-RPC error. Phone/IP provider failures are refunded; polling is free. For OCR reuse Idempotency-Key only with the same image; do not create duplicate billable jobs while polling. OCR extracts fields and format checks; it does not confirm identity, document authenticity or МВД validity.

## Current prices and quotas

```json
[
    {
        "code": "phone",
        "name": "Телефон и время",
        "enabled": true,
        "free_limit": 100,
        "free_period": "month",
        "plans": [
            {
                "code": "start",
                "name": "Старт",
                "price_kopecks": 29900,
                "monthly_limit": 10000
            },
            {
                "code": "pro",
                "name": "Про",
                "price_kopecks": 99000,
                "monthly_limit": 100000
            }
        ]
    },
    {
        "code": "geoip",
        "name": "IP и местное время",
        "enabled": true,
        "free_limit": 100,
        "free_period": "month",
        "plans": [
            {
                "code": "start",
                "name": "Старт",
                "price_kopecks": 29900,
                "monthly_limit": 10000
            },
            {
                "code": "pro",
                "name": "Про",
                "price_kopecks": 99000,
                "monthly_limit": 100000
            }
        ]
    },
    {
        "code": "ocr",
        "name": "Распознавание документов",
        "enabled": true,
        "free_limit": 10,
        "free_period": "lifetime",
        "plans": [
            {
                "code": "start",
                "name": "Старт",
                "price_kopecks": 39000,
                "monthly_limit": 1000
            },
            {
                "code": "pro",
                "name": "Про",
                "price_kopecks": 290000,
                "monthly_limit": 10000
            }
        ]
    }
]
```