IP Intelligence for AI Agents: MCP Integration Guide (2026)

AI agents keep running into the same question: where is this IP address, and who owns its network? Until recently the answer meant hand-rolled API clients, bespoke prompts, and a different integration for every agent framework. The Model Context Protocol (MCP) collapses that into one pattern: register a server, let the agent discover its tools, and call them as JSON-RPC.

IP-Info.app ships a hosted MCP server at https://api.ip-info.app/mcp. It exposes the same geolocation and ASN data as the REST API behind two read-only tools. This guide covers why agents need IP intelligence, how to connect a client, what ip_get_details actually returns, and how credit billing behaves inside an agent loop.

Where agents use IP intelligence

Three agent workflows come up again and again in production. Each one needs trusted network context at decision time, not a stale lookup cached at session start.

In all four cases the tool is evidence, not verdict. An agent should surface the signals and let policy code or a human decide, the same separation the agentic IP risk guardrails guide recommends.

Connect a client in one config block

The server speaks Streamable HTTP transport: every request is a POST carrying a JSON-RPC 2.0 body and the header Accept: application/json, text/event-stream. MCP clients that support http-type servers handle the session for you once registered:

{
  "mcpServers": {
    "ip-info": {
      "type": "http",
      "url": "https://api.ip-info.app/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Authentication rides on the x-api-key header with an IP-Info API key, created under Account → API keys. Keys are host-scoped to IP-Info.app, so a key issued for another product in the ecosystem is rejected rather than silently falling back. For a trial before signing up, the demo key demo-key works with a valid TOTP passed in the x-ct header, subject to demo rate limits.

Prefer to inspect the raw protocol first? Initialize a session by hand and read what the server announces:

curl -X POST 'https://api.ip-info.app/mcp' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

The initialize result lists the server capabilities and includes agent instructions describing the auth and billing contract. Well-behaved clients surface those instructions to the model, so the agent learns the rules on connect instead of discovering a 402 mid-run.

Calling ip_get_details over JSON-RPC

The workhorse tool is ip_get_details. A tool call sends the method tools/call with the tool name and arguments:

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

The result arrives as MCP tool content — a text payload carrying the lookup. Asking about Google's public resolver returns country US, ASN 15169, and organization Google LLC:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ip\":\"8.8.8.8\",\"ptr\":\"dns.google\",\"city\":{\"name\":\"Mountain View\",\"region\":\"California\",\"latitude\":37.4223,\"longitude\":-122.085,\"accuracyRadius\":1000,\"timeZone\":\"America/Los_Angeles\"},\"continentCode\":\"NA\",\"countryName\":\"United States\",\"countryCode\":\"US\",\"registeredCountryCode\":\"US\",\"asn\":15169,\"aso\":\"Google LLC\",\"organization\":\"Google LLC\"}"
      }
    ]
  }
}

Omit the ip argument and the tool resolves the caller's own address — useful when an agent needs its egress context. An optional provider argument accepts maxmind (default) or geojs. Both tools advertise readOnlyHint and idempotentHint, so retries are safe and side-effect free. The second tool, account_whoami, is a free identity probe returning the account behind the key.

An agent workflow that respects the credit budget

A signup-screening agent can combine both tools cheaply: probe the account for free, enrich once, then hand the evidence to policy code that already exists:

async function screenSignup(mcp, apiKey, signupIp) {
  // 1. Free probe: does the account have credits?
  const who = await mcp.callTool('account_whoami', {});

  // 2. Enrich the signup with network context.
  const details = await mcp.callTool('ip_get_details', { ip: signupIp });

  // 3. Let policy, not the agent, make the decision.
  const risk = evaluatePolicy({
    countryCode: details.countryCode,        // 'US'
    registeredCountryCode: details.registeredCountryCode,
    asn: details.asn,                        // 15169
    organization: details.organization,      // 'Google LLC'
  });

  return risk.allow
    ? { action: 'approve', reason: risk.reason }
    : { action: 'review', reason: risk.reason };
}

Two rules keep this honest in production. First, the agent reports evidence and a recommended action; approval logic stays in reviewed policy code. Second, the agent checks account_whoami before long batch runs so an empty balance produces one clean message instead of hundreds of failures.

Billing: one credit per tool call

Each successful ip_get_details call costs one credit. account_whoami is free, so identity probes and balance checks never drain a budget. When the account runs out, calls return HTTP 402 PAYMENT_REQUIRED — teach the agent to stop and point the operator at pricing rather than retrying. The same contract ships in the initialize instructions, so clients that respect it degrade gracefully.

Discovery surfaces

Beyond the endpoint itself, IP-Info.app publishes machine-readable discovery for agent runtimes: /llms.txt summarizes the product and MCP surface for LLM crawlers, /.well-known/mcp/server-card.json describes the server for MCP-aware clients, and the interactive API reference includes a Scalar MCP panel that connects to the server in one click. A step-by-step client walkthrough also lives in the MCP server guide.