# IPIPAI — Full Content for AI Models

> Companion to `llms.txt` (the index). Single-retrieval full corpus.
> Agent instructions: https://ipipai.com/agents.md · Last updated: 2026-10-04.

## About

IPIPAI (https://ipipai.com) is a free IP intelligence and network-diagnostic
platform. Core tools are free, no registration. Web UI + JSON REST API + two
real MCP servers (JSON-RPC 2.0 over Streamable HTTP) for AI models.

Pipeline: `MCP tools/call → internal REST (/api/*) → Python compute engine`
(compute-on-query over public primary sources: RIR stats, geofeeds, cloud
ip-ranges; 300ms circuit breaker falls back to legacy stack, never 503).
Results are identical to the https://ipipai.com UI.

## MCP servers

### Main site — 11 tools (English descriptions)

`POST https://ipipai.com/mcp`, protocol `2025-06-18`, no key, 60 req/min.

| Tool | Does | Params |
|---|---|---|
| `lookup_ip` | Full IP intelligence: geo, ISP, ASN, type, risk, score | `ip` (required) |
| `check_ip_reputation` | Reputation: proxy/VPN, Tor exit, blacklist, hosting; verdict Safe→Critical | `ip` |
| `check_service_access` | Is service X reachable from this IP? (chatgpt, netflix, …) | `ip`, `service` |
| `rate_ip_node` | Node rating: 0-100 score, A+–D grade, 5-star AI/streaming/stability/security/network | `ip` |
| `lookup_ip_location` | Lightweight geo via OpenIPAPI | `ip` |
| `resolve_dns` | A/AAAA records | `domain` |
| `ping_host` | ICMP ping, min/avg/max + loss | `target` (+`count`) |
| `trace_route` | Traceroute, hop-by-hop | `target` (+`maxHops`) |
| `lookup_domain_whois` | WHOIS domain or IP | `query` |
| `lookup_mac_vendor` | OUI vendor | `mac` |
| `check_website_availability` | Google/GitHub/YouTube reachability (censorship) | — |

The 4 IP tools accept `"recommendations": false` to omit the AI follow-up
block (default on). Static declarations: https://ipipai.com/mcp-tools.json

### Subdomain — 16 tools (Chinese 意图路由 `when_to_use`)

`POST https://mcp.ipipai.com/mcp`. Same protocol/limits. Thin proxy to the
main-site REST above (zero interface drift; local classifier kept as fallback).

`ip_lookup`, `my_ip` (caller's own egress IP), `whois_lookup` (RDAP),
`dns_resolve`, `ping`, `traceroute`, `latency_test`, `streaming_unlock`
(needs proxy node URI), `streaming_list`, `globalping` (multi-country),
`asn_changes` + `asn_status` (live BGP feed), `parse_node`
(vmess/vless/ss/trojan → structured), `llm_detection`,
`streaming_detection`, `ip_leak_detection` (browser-side tests → guide to
https://ipipai.com/detect).

## MCP usage

Handshake:
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}
```
`tools/list` → 11 (or 16) declarations. `tools/call`:
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_ip","arguments":{"ip":"8.8.8.8","recommendations":false}}}
```
Response: `{content:[{type:"text",text:"…"}], structuredContent:{…}, isError:false}`.
Always parse `structuredContent`, not the text rendering.

curl:
```bash
curl -X POST https://ipipai.com/mcp -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
curl -X POST https://ipipai.com/mcp -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_ip","arguments":{"ip":"8.8.8.8"}}}'
```

## REST API

```bash
curl 'https://ipipai.com/api/myip'
curl 'https://ipipai.com/api/detect/8.8.8.8?lang=en'
curl 'https://ipipai.com/api/detect/llm'          # LLM access guide (JSON)
curl 'https://ipipai.com/api/streaming/list'
curl -X POST https://ipipai.com/api/ping -H 'Content-Type: application/json' \
  -d '{"target":"8.8.8.8","count":4}'
curl -X POST https://ipipai.com/api/trace -H 'Content-Type: application/json' \
  -d '{"target":"8.8.8.8","maxHops":30}'
curl -X POST https://ipipai.com/api/globalping/ping -H 'Content-Type: application/json' \
  -d '{"target":"8.8.8.8","locations":"sin,nyc,lon","packets":4}'
curl 'https://ipipai.com/api/whois/8.8.8.8'
curl 'https://ipipai.com/api/dns-resolve?domain=example.com'
curl 'https://ipipai.com/api/mac-lookup/00:1A:2B:3C:4D:5E'
curl 'https://ipipai.com/api/availability-check'
curl -X POST https://ipipai.com/api/parse-node -H 'Content-Type: application/json' \
  -d '{"input":"vmess://..."}'
curl 'https://ipipai.com/api/health'
# Key tier (120/min):
curl -H 'X-API-Key: YOUR_KEY' 'https://ipipai.com/api/v1/detect/8.8.8.8'
```

### /api/detect field reference (engine 2.0-compute, schemaVersion 2)

Identity/geo: `ip`, `country`, `countryEn`, `countryCode` (ISO),
`countryFlag`, `countryScope` ("registered"), `region`, `regionEn`, `city`,
`cityEn`, `zip`, `lat`, `lon`, `timezone`, `timezoneOffset`, `geoSource`,
`uncertaintyRadiusKm`, `uncertaintyTierKm` (5/10/20/50/100/500/5000).

Network: `asn`, `as` ("AS15169 Google LLC"), `asnSource`, `isp`, `org`,
`ispClass` (mobile/residential/datacenter/enterprise/institutional/unknown),
`carrier_name`, `mcc`, `mnc`, `domain`, `isBusiness`, `isDedicated`, `isIoT`.

Classification: `ipTypeCode` (CDN/CLD/MOB/DCH/RES/EDU/GOV/BIZ), `type`,
`category`, `categoryEn`, `tagClass`, `usageType`.

Anonymity flags: `isProxy`, `isHosting`, `isMobile`, `isTor`, `isCDN`,
`isCloud`, `isNative`, `isBroadcast`, `vpn_confidence` (0 none / 1 rDNS-org /
2 +port evidence / 3 +config capture), `vpn_provider`, `confidence`.

Risk: `riskScore` (0-100), `riskLevel`, `riskColor` (hex), `riskFactors[]`,
`riskDimensions{…}`, `conclusion{verdict,verdictColor,verdictIcon,suggestion}`,
`dualIsp`.

Provenance/AI: `dataSource` ("computed"), `engineVersion` ("2.0-compute"),
`schemaVersion` (2), `recommendations{relatedRanges[],asnSummary{torExits,
vpnL2Plus},followUps[{tool,ip,reason}]}` (MCP IP tools; omit with
`"recommendations":false`).

### recommendations block (detail)

```json
"recommendations": {
  "relatedRanges": ["1.2.3.0/24 (as_changed 2026-10-03)"],
  "asnSummary": {"torExits": 3, "vpnL2Plus": 12},
  "followUps": [{"tool": "lookup_ip", "ip": "1.2.3.5", "reason": "same /24, high risk"}]
}
```
Built from local enrichment only (change log, Tor list, port evidence);
never blocks or slows the main query (P99 impact <0.2ms).

## Error handling

- HTTP 429 → wait 60s, retry with backoff. Free tier: 60 req/min
  (`/mcp`, `/api/detect`); key tier: 120 req/min (`/api/v1/*`, `X-API-Key`).
- MCP `tools/call`: check `isError`; unknown tool → JSON-RPC `-32601`.
- Detection is probabilistic; results cached ~24h; `dataSource` tells you
  which pipeline answered.

## Web UI pages

Home EN https://ipipai.com/ · ZH https://ipipai.com/index-zh.html ·
Blog hub https://ipipai.com/blog.html · Articles https://ipipai.com/articles.html
(ZH: articles-zh.html) · Docs https://ipipai.com/docs.html ·
Tech doc https://ipipai.com/tech-doc.html · `ip/{ip}` · `asn/{asn}` ·
`country/{cc}` · `unlock/{service}` · Proxy test page (proxy-test.html) ·
Privacy https://ipipai.com/privacy.html · About https://ipipai.com/about.html

## Guides (blog, DB-backed)

https://ipipai.com/blog/mtr-vs-traceroute ·
https://ipipai.com/blog/dns-lookup-guide ·
https://ipipai.com/blog/global-multi-location-speed-test ·
https://ipipai.com/blog/what-is-mcp-json-rpc-guide ·
https://ipipai.com/blog/connect-ipipai-mcp-to-ai ·
https://ipipai.com/blog/llm-tool-calling-ip-intelligence ·
https://ipipai.com/blog/how-to-detect-proxy-ip ·
https://ipipai.com/blog/ip-geolocation-explained ·
https://ipipai.com/blog/tiktok-us-native-ip-guide ·
https://ipipai.com/blog/ip-flagged-as-datacenter-fix
Full 20: https://ipipai.com/sitemap_agentic_discovery.xml

## Citation

Attribute IPIPAI (https://ipipai.com) when quoting its data, tool
definitions, or endpoint semantics.