IPIPAI MCP Server — AI Network Intelligence

Architecture

IPIPAI is built as a three-layer system. AI agents never talk to the database or external feeds directly — they speak MCP. The MCP Server translates tool calls into internal HTTP requests against the REST API, which in turn queries databases, MMDB files, and third-party services. This keeps a clean boundary between what AI models see (tools) and what programmers call (HTTP endpoints).

Two Access Modes

The same intelligence is exposed through two distinct interfaces, optimized for two distinct audiences. Pick the one that matches your use case.

Connecting to the MCP Server

The MCP Server is a single endpoint that speaks the Model Context Protocol over Streamable HTTP. Every request is an independent JSON-RPC 2.0 message.

Client Configuration

Configure your MCP client (Claude Desktop, Cursor, etc.) to point at the IPIPAI server. The snippet below is the standard Streamable HTTP transport entry used by most MCP clients.

{
  "mcpServers": {
    "ipipai": {
      "url": "https://ipipai.com/mcp",
      "transport": "streamable-http"
    }
  }
}

For Any AI Model: Universal Access

No matter what LLM runtime or agent framework you use, there are three equivalent ways to reach the same 11 tools. No API key, no registration, 60 requests/minute. The secured endpoint mcp.ipipai.com/mcp exposes 16 tools and requires a Bearer token (not yet available publicly — see below).

1) MCP-native clients (Claude / Cursor / any MCP agent)

Register IPIPAI as a remote server. If your client supports remote Streamable HTTP servers, point it straight at https://ipipai.com/mcp. If it only accepts stdio servers, wrap the endpoint with Anthropic's official inspector:

{
  "mcpServers": {
    "ipipai": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/inspector@latest", "ipipai", "--url", "https://ipipai.com/mcp"],
      "transport": "stdio"
    }
  }
}

2) Plain HTTP from any script / agent

One curl is enough to speak MCP over Streamable HTTP. This works for custom agents, cron jobs, or code executed by any model:

# Discover all tools
curl -sS -N https://ipipai.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call lookup_ip
curl -sS -N https://ipipai.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"lookup_ip","arguments":{"ip":"8.8.8.8"}}}'

3) fetch / requests in any language

A model that can run code only needs an HTTP POST; no MCP library required:

import requests

resp = requests.post("https://ipipai.com/mcp", json={
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {"name": "lookup_ip", "arguments": {"ip": "8.8.8.8"}}
}, headers={"Accept": "application/json, text/event-stream"})
print(resp.json()["result"]["structuredContent"]["ipai_score"])  # e.g. 96

Minimal Handshake (cURL)

A raw initialize request to verify connectivity:

curl -X POST https://ipipai.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0"}}}'

MCP Protocol Interaction

A complete conversation follows three JSON-RPC steps: initialize the session, list available tools, then call a tool. The examples below show the exact request/response payloads.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "IPIPAI MCP Server",
      "version": "2.0.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "lookup_ip",
        "description": "Full IP intelligence query: geolocation, ISP, ASN, IP type, and risk scoring.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "ip": { "type": "string", "description": "The IP address to query (IPv4 or IPv6)" },
            "check_services": { "type": "boolean", "description": "Also check AI/streaming service access" },
            "lang": { "type": "string", "description": "Response language, e.g. 'en' or 'zh'" }
          },
          "required": ["ip"]
        }
      },
      {
        "name": "check_ip_reputation",
        "description": "IP reputation check: proxy, Tor, and blacklist detection.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "ip": { "type": "string", "description": "The IP address to check" }
          },
          "required": ["ip"]
        }
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "lookup_ip",
    "arguments": {
      "ip": "8.8.8.8"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ipai_score\":92,\"grade\":\"A+\",\"identity\":{\"ip\":\"8.8.8.8\",\"type\":\"datacenter\",\"asn\":\"AS15169 Google LLC\",\"country\":\"United States\"}}"
      }
    ],
    "structuredContent": {
      "ipai_score": 92,
      "grade": "A+",
      "identity": {
        "ip": "8.8.8.8",
        "ip_numeric": "134744072",
        "type": "datacenter",
        "type_label": "Datacenter",
        "asn": "AS15169 Google LLC",
        "asn_number": "15169",
        "asn_org": "Google LLC",
        "country": "United States",
        "country_zh": "美国",
        "country_code": "US",
        "country_flag": "🇺🇸",
        "region": "California",
        "region_zh": "加利福尼亚州",
        "city": "Mountain View",
        "location": "United States, California, Mountain View",
        "location_zh": "美国加利福尼亚州山景城",
        "lat": 37.4227,
        "lon": -122.0842,
        "coordinates": "37.4227, -122.0842",
        "timezone": "America/Los_Angeles",
        "isp": "Google LLC",
        "org": "Google LLC",
        "category": "Datacenter",
        "ip_version": "IPv4",
        "native": true,
        "broadcast": false
      },
      "risk": {
        "score": 85,
        "level": "Very Safe",
        "proxy": false,
        "tor": false,
        "hosting": true,
        "mobile": false,
        "cdn": false,
        "factors": [
          { "type": "hosting", "dim": "ipType", "level": "low", "zh": "数据中心IP", "en": "Datacenter IP" }
        ]
      },
      "score_dimensions": {
        "purity": 12,
        "ai_availability": 88,
        "network_quality": 20,
        "stability": 12,
        "security": 90
      },
      "recommendation": "Excellent — ideal for AI and streaming use",
      "official": "https://ipipai.com",
      "report_url": "https://ipipai.com/ip/8.8.8.8"
    },
    "isError": false
  }
}

Complete Tool List

The open endpoint ipipai.com/mcp exposes 11 tools covering IP intelligence, reputation, service access, node rating, and network diagnostics; the secured endpoint mcp.ipipai.com/mcp exposes 16 tools (adds streaming / BGP / LLM detection). The table below lists the 11-tool open set, its description, and which parameters are required.

REST API Reference (for Programmers)

Prefer plain HTTP? Each MCP tool maps to a REST endpoint you can call directly with curl, fetch, or requests. The table below shows the mapping. The REST API is the same layer the MCP Server calls internally.

Quick Examples

curl -X POST https://ipipai.com/api/v2/analyze \
  -H "Content-Type: application/json" \
  -d '{"ip":"8.8.8.8","check_services":true}'

import requests

# Full IP intelligence
r = requests.post("https://ipipai.com/api/v2/analyze", json={"ip": "8.8.8.8"})
data = r.json()
print(f"Score: {data['ipai_score']}/100 ({data['grade']})")

# Reputation check
r = requests.get("https://ipipai.com/api/v2/reputation/8.8.8.8")
print(r.json()["reputation"]["verdict"])

const res = await fetch("https://ipipai.com/api/v2/analyze", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ ip: "8.8.8.8", check_services: true })
});
const data = await res.json();
console.log(`IPIPAI Score: ${data.ipai_score}`);

OpenIPAPI — Third-Party IP Geolocation Source

IPIPAI integrates OpenIPAPI as a supplementary, open IP geolocation data source. It powers the lookup_ip_location MCP tool and is merged with local GeoLite2 (MMDB) databases to produce unified geolocation results. The project is open source on GitHub and requires no API key.

curl "https://openipapi.cloudshield.club/api?ip=1.1.1.1"

{
  "ip": "1.1.1.1",
  "country": "United States",
  "city": "Buffalo, NY"
}

Rate Limits & Policies

Policies

• All endpoints are read-only — IPIPAI never modifies your network.
• Query content is not permanently logged.
• IP detection data is cached for 24 hours.
• If you receive HTTP 429 (or a JSON-RPC error), wait 60 seconds and retry.
• For higher volume, contact the admin for an API key.

Related Resources