IPGeolocation MCP Server

Bulk User-Agent Parser

bulk_parse_user_agent

Read-only

Instructions

Read-only bulk user-agent parsing via POST /v3/user-agent-bulk. Paid only. Cost: 1 credit per successful string. This MCP server accepts up to 250 explicit user-agent strings. 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.

Returns one parsed object per string with user_agent_string, name, type, version, version_major, device, engine, and operating_system. uaStrings must be a non-empty array of exact user-agent strings; empty/null strings are rejected locally before any API call. parse_user_agent handles a single string. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.

Input Schema

Name	Required	Description	Default
`uaStrings`	Yes	Array of user-agent strings to parse. Minimum 1, maximum 250 in this MCP server.
`force_refresh`	No	Default false. When true, bypasses cached bulk user-agent parsing 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.16May 11, 2026
- addedInput schema / properties / uaStrings / items / minLength
```
Added value: +1
```

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 user-agent parsing data; a successful refresh makes a new upstream request and can consume credits."

First observedv1.0.10Mar 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint/openWorldHint annotations: paid-only access at 1 credit per successful string, a hard 250-string ceiling enforced locally, local rejection of empty/null strings, caching plus page.next_cursor retrieval without another API call, and the credit cost of force_refresh. Credit consumption is a billing side effect, not a write, so it does not conflict with readOnlyHint.

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?

Front-loaded with the cost and size constraints an agent most needs, then return shape, then parameter notes. It is dense and mostly earns its length, though the 250 limit is stated twice and the return-field list duplicates the output schema.

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?

Covers cost model, size limits, local validation, caching/pagination escape hatch, parameter flags, and the single-string alternative. With an output schema present the return-value enumeration is redundant but harmless; nothing an agent needs to call this correctly is missing.

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 the baseline is 3, but the description adds real meaning: uaStrings must be non-empty exact user-agent strings (not patterns), are validated locally, and force_refresh both bypasses the cache and incurs credits. It largely restates the schema's min/max bounds, which caps it below 5.

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 and resource (bulk user-agent parsing) plus the upstream endpoint POST /v3/user-agent-bulk. It explicitly distinguishes itself from the sibling parse_user_agent, which handles a single string, so an agent can choose between them 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?

Names alternatives and the conditions selecting them: parse_user_agent for single strings, get_cached_result for oversized/paged results. It also tells the agent when force_refresh is warranted and what it costs, and warns that batches over 250 are rejected before any API call.

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

Deploy Server