IPGeolocation MCP Server

Bulk Security Check

bulk_security_check

Read-only

Instructions

Read-only bulk security lookup via POST /v3/security-bulk. Paid only. Cost: 2 credits per valid IP. This MCP server accepts up to 250 IPs; private, bogon, and malformed IPs are not billed. Larger batches are rejected before any API call. Complete results are returned directly or as cached pages. Oversized results contain page.next_cursor for complete retrieval through get_cached_result without another API call or additional credits.

This endpoint is dedicated to security-only batches; bulk_lookup_ip with include=security provides security data together with geolocation or other IP domains. Returns one { ip, security } result per valid IP. fields/excludes accept security.* dot paths per item. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.

Input Schema

Name	Required	Description
`ips`	Yes	Array of IPv4 and/or IPv6 addresses to check. Minimum 1, maximum 250 in this MCP server.
`fields`	No	Comma-separated dot-path fields to return per IP (e.g. security.threat_score,security.is_vpn). Reduces response size.
`excludes`	No	Comma-separated dot-path fields to exclude per IP (e.g. security.is_tor,security.is_cloud_provider).
`force_refresh`	No	Default false. When true, bypasses cached bulk security data; a successful refresh makes a new upstream request and can consume credits.

Output Schema

Name	Required	Description
`page`	No
`error`	No	Present when the whole tool call fails, with isError: true.
`items`	No	Present on success: complete API results in input order, including any per-item error messages.
`errors`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.0.3Oct 28, 2026

removedOutput schema / properties / items / items / additionalProperties / anyOf

Removed value: -[
-  {
-    "type": "null"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "array"
-  },
-  {
-    "type": "object"
-  }
-]

addedOutput schema / properties / items / items / additionalProperties / type

Added value: +[
+  "null",
+  "boolean",
+  "number",
+  "string",
+  "array",
+  "object"
+]

Addedv2.0.1Oct 13, 2026
Removedv2.0.0Jul 25, 2026

Changed1 schema field changedv1.0.15May 8, 2026

changedInput schema / properties / force_refresh / description

Previous value: -"Default false. Leave unset unless the user asks to refresh or rerun."New value: +"Default false. Set true only when the user asks to refresh cached bulk security data; a successful refresh makes a new upstream request and can consume credits."

First observedv1.0.10Mar 16, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint; the description adds the economically critical behaviour: paid-only, 2 credits per valid IP, private/bogon/malformed IPs unbilled, and force_refresh causing a fresh upstream call that can consume credits. It also discloses paging via page.next_cursor that costs no extra credits. The only gap is that 'read-only' coexists with credit consumption without saying whether repeated identical calls are billed again when cache hits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Cost, batch limit, and the sibling alternative are front-loaded in the first two sentences, with paging and parameter notes after. Dense and mostly waste-free, though the credit/caching story is split across two paragraphs and could be stated once.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return-shape explanation is unnecessary, and the description still covers billing model, batch ceiling, invalid-input handling, pagination, and sibling differentiation. For a 4-parameter, paid, open-world tool, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real value: fields/excludes operate on security.* dot paths per item, which tightens the broader schema examples, and it frames force_refresh as both a cache bypass and a billing event. Remaining parameter nuance (interaction of fields and excludes, invalid dot-path handling) is left unstated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: 'Read-only bulk security lookup via POST /v3/security-bulk', and immediately distinguishes the tool from its nearest sibling by naming bulk_lookup_ip with include=security as the combined-domain alternative. An agent can pick correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: use this endpoint for security-only batches, use bulk_lookup_ip when security must be combined with geolocation or other domains, and use get_cached_result to page oversized results. It also states the hard exclusion boundary (batches over 250 rejected before any API call), which is a when-not condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server