Do I need an API key?

Not to start. Without a key, 8 of the 21 tools work: lookup_ip runs on the keyless demo (IP addresses only, about 100 a day), verify_crawler uses the public sample, and the ASN directory and every guide are open. Add a key for the rest.

Where does my key go?

Your client sends it as an Authorization header on each call. The server passes it to the IPScanner API for that one request and never stores it. Usage shows up on your dashboard like any other key.

Can a tool change anything in my account?

One can: provenance_check appends an attestation to your audit log, because that is what an attestation is. Every other tool only reads. Clients that show tool annotations will mark it as a write.

Which transport does it use?

Streamable HTTP, stateless, with plain JSON responses. There is no session to keep alive, so it works behind any proxy and from any client that supports remote MCP servers. Desktop apps that only speak stdio can connect through mcp-remote.

IPScanner

Model Context Protocol

The MCP server for IP detection and bot defense

Give Claude, Cursor, VS Code or any MCP client the whole IPScanner engine. Your agent can ask whether an address is a VPN or Tor exit, check that Googlebot is really Google, seal an age-gate decision, and read the guides it needs to wire the API into your code.

https://ipscanner.io/api/mcp

Get a free API key Connect your client

8 of 21 tools work before you sign up. The free plan is 30,000 requests a month.

ipscanner.io/api/mcpStreamable HTTP

AgentYour agentMCPIP Detection

New signup from 185.220.101.1. Should we let it through?

Tool calllookup_ipCalling200 OK

{ "target": "185.220.101.1" }"classification": "tor","anonymized": true,"isTor": true,"confidence": 1

Tor exit

No. It is a Tor exit node, so the person behind it is anonymized. Refuse the signup or ask for a verified email.

Setup

One URL, one header

The server is hosted, so there is nothing to install or keep running. Point your client at the URL and pass your API key as a Bearer header. Skip the header and it still connects, with the keyless tools.

Your key goes to the IPScanner API for that one call and is never stored by the MCP server.
Calls show up on your usage page next to the key that made them.
Stateless HTTP: no session to drop, nothing to reconnect.

Run in your terminal

claude mcp add --transport http ipscanner https://ipscanner.io/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Leave out --header to start keyless. Run /mcp inside Claude Code to check the connection.

Tools

21 tools across three products

Each metered tool spends one request from the same monthly allowance as the REST API. Everything marked free costs nothing, even at 100%.

IP Detection

What kind of network an address belongs to, where it is and who runs it.

lookup_ipWorks keyless1 request
Everything at once for an IP, CIDR, hostname or URL: class, confidence, purity, geo, ASN, WHOIS.
check_vpn1 request
Network class, anonymized flag and risk score.
check_proxy1 request
The same verdict framed as proxy, Tor included.
get_geolocation1 request
Country down to postal code, coordinates and timezone.
get_asn1 request
The autonomous system that owns the address.
whois_lookup1 request
Registrar, dates, nameservers and status for a domain.
bulk_lookup1 request
Up to a thousand addresses in one call, summarised by class.

Agentscan

Human, verified crawler, AI agent or malicious automation.

agentscan_check1 request
A verdict and an allow, flag or block action for one request.
verify_crawlerWorks keyless1 request
Is that really Googlebot? Checked against what the operator publishes.
agentscan_allowlistFree
The verified crawlers in effect for your account.

Provenance

Location attestation with a hash-chained audit log.

provenance_check1 request
Apply a jurisdiction policy and seal the decision into your audit log.
provenance_jurisdictionsFree
The policy table: Utah, UK, Australia, EU and the default.
provenance_verify_chainFree
Recompute every hash and report the first broken link, if any.
provenance_exportFree
Signed evidence CSV for a date range.

Directory and account

Public reference data and your own allowance.

search_asnNo keyFree
Find a network by name or number, or list the largest.
get_asn_detailsNo keyFree
Prefixes, address count and network type for one ASN.
get_usageFree
Plan, requests used, requests left and the reset date.

Implementation guides

What your coding agent reads before it writes the integration.

list_guidesNo keyFree
Every guide with a one-line summary.
get_guideNo keyFree
One guide as Markdown, with code for Node, Next.js, Python and Go.
search_docsNo keyFree
Full-text search across the guides.
get_code_sampleNo keyFree
A ready request for any endpoint in six languages.

Implementation guides

Your coding agent reads the manual first

The guides are written for the model as much as for you: which endpoint to pick, how to find the real client IP behind a proxy, why a cloud address is not a VPN, what to do with each 429. They carry working code for Node, Next.js, Python and Go.

Quickstart
Base URL, the keyless demo, your first keyed call and what comes back.
Authentication and key handling
Bearer keys, where to keep them, and the two 401 codes.
Reading networkClass correctly
What each network class means, why hosting is not VPN, and a decision table.
Build a VPN and proxy gate
Server-side gate for signup, login or checkout with client-IP extraction, timeouts and caching, in Node, Next.js, Python and Go.
Agentscan: bot and AI-agent defense
Edge snippet plus server-side check, the four verdict classes and the allow/flag/block action.
Verify a crawler claim
Is this address really Googlebot or GPTBot? Outcomes and why unverifiable is not spoofed.
Provenance: location attestation and audit trail
Age and geo gates with per-jurisdiction policy, a hash-chained audit log and evidence export.
Bulk lookups
POST /v1/ip/bulk, the per-plan batch cap and reading the NDJSON stream.
Rate limits, quota and errors
The pooled monthly allowance, rate-limit headers, the three 429 reasons and a retry strategy.

The integrate_ipscanner prompt

Pick a use case and your stack. The prompt tells the agent which guides to read, what to look for in your project, and the rules the integration has to follow: key server-side only, a timeout, a failure policy, tests.

signup_gateVPN, proxy and Tor gate on signup and login
checkout_fraudRisk checks on checkout and payments
bot_defenseBot and AI-agent defense with Agentscan
age_gateAge or geo gate with Provenance attestations
enrichmentEnrich users and events, including bulk backfills

In Claude Code

/mcp__ipscanner__integrate_ipscanner signup_gate "Next.js 15"

Without a key

Try it on real addresses

lookup_ip on the keyless demo, about 100 addresses a day
verify_crawler on the public sample, 5 checks an hour
The ASN directory and every implementation guide

With a key

Everything, on your allowance

Hostnames, CIDRs and URLs on lookup_ip, plus bulk up to your plan's cap
Agentscan verdicts, your allowlist and Provenance attestations
30,000 requests a month on the free plan, shared with the REST API

See plans

Questions

MCP server FAQ

No. It spends the same pooled allowance as the REST API: one request per metered tool call, one per address on bulk_lookup. Reads, directory search and every guide tool are free. The free plan is 30,000 requests a month.

Put IP detection in your agent's hands

Create a key, paste one config block, and ask your first question.

Get a free API key Read the API docs