IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/security.ts:80-110 (handler)

  The handler function that executes the `check_security` tool logic.

    async (params) => {
      try {
        const cacheKey = buildSecurityCacheKey(params.ip);
        const cached = params.force_refresh ? undefined : getCachedValue(cacheKey);
  
        const baseResult =
          cached ??
          (await getSecurity({
            ip: params.ip,
          }));
  
        if (cached === undefined) {
          setCachedValue(cacheKey, baseResult);
        }
  
        const result = applyFieldsAndExcludes(baseResult, {
          fields: params.fields,
          excludes: params.excludes,
          rootKey: "security",
        });
  
        return {
          content: [
            { type: "text" as const, text: formatToolResult(result) },
          ],
        };
      } catch (error) {
        return errorToolResponse(error);
      }
    }
  );

• src/tools/security.ts:42-78 (registration)

  The registration and schema definition for the `check_security` tool.

    server.registerTool(
      "check_security",
      {
        title: "VPN/Proxy/Threat Detection",
        annotations: {
          readOnlyHint: true,
        },
        description: `Decision policy: this is a single-domain tool. Use it only when the user asks for security/threat data only. If the same IP request also needs ownership/company/ASN, location/city, network, timezone, currency, or abuse data, call lookup_ip once with include and targeted fields/excludes instead of chaining tools.
  
  Dedicated IP security lookup via GET /v3/security. Paid only. Cost: 2 credits. Returns threat score plus VPN, proxy, Tor, bot, spam, attacker, relay, anonymity, and cloud-provider indicators.
  
  Use lookup_ip with include=security when the same request also needs other IP domains. Tool selection rule: if this tool is used, call it once per IP target and post-process locally. Do not re-call check_security for the same IP just to change fields/excludes or to reformat output.`,
        inputSchema: {
          ip: z
            .string()
            .optional()
            .describe(
              "IPv4 or IPv6 address to check. Omit to check the caller's IP."
            ),
          fields: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to return (e.g. security.threat_score,security.is_vpn). Reduces response size."
            ),
          excludes: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to exclude (e.g. security.is_tor,security.is_cloud_provider)."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },
      },