On this page
You have yesterday's signups in a CSV, and you want to know which accounts came through a residential proxy, a VPN or Tor, without writing a script. The VPNDetection plugin for Claude gives Claude our API as tools, and four skills that tell it how to use them, so the answer comes back as a table of accounts rather than a list of addresses. We ran every question below in Claude Code 2.1.303, with the plugin's 1.2.1 skills and Claude Sonnet 5.5, against the live server on October 24, 2026. Claude's answers are quoted as it gave them, with the home and proxy addresses withheld. claude.ai and the desktop app connect to the same server; we didn't run them, so their steps below follow Anthropic's guide to custom connectors.
Install it
In claude.ai, the desktop app and Cowork
Go to Customize > Connectors, click + Add, then Add custom connector. Name it VPNDetection, enter our server's URL and click Continue, then Continue again past the authentication settings Claude detected:
https://mcp.vpndetection.io/mcp
Under Authentication choose Sign in now, and under OAuth client choose Use Claude's published identity: there's no client ID or secret to enter. Click Add, sign in with your VPNDetection account, pick which of your organization's API keys Claude should use, and approve. Then turn it on for a chat under + > Connectors.
Custom connectors work on every Claude plan; Free allows one. On a Team or Enterprise plan, an Owner adds it once under Organization settings > Connectors, through Add and Custom > Web, and each member then connects with their own account. A connector brings the tools alone. The skills come with the plugin.
In Claude Code
/plugin marketplace add vpndetection-io/claude-plugin
/plugin install vpndetection@vpndetection
The first time one of its tools runs, Claude Code asks you to sign in. On a machine where nobody can, such as a CI runner, it takes an API key in a header instead:
claude mcp add --scope user --transport http \
vpndetection https://mcp.vpndetection.io/mcp \
--header "Authorization: Bearer $VPNDETECTION_API_KEY"The runs below connected with a key that way, since nobody was at the sign-in screen.
What signing in sends
You sign in with your VPNDetection account and pick one of your organization's API keys. Approving needs permission to share that organization's keys, and asks you to confirm it's you. Claude never sees the key: our server uses it on your behalf, so every lookup counts against that key's plan like any other API call. Claude sends us the IP addresses and database ids you ask about.
To disconnect, remove Claude under Settings > Sessions & devices > Connected applications in the console. Access ends within about a minute.
Screening a signup export
Our test export, signups.csv, has 13 rows with the columns user_id, email, created_at and signup_ip. The accounts are made up and the addresses are real: five home broadband lines, three residential proxy exits, one Mullvad server shared by two accounts, a Tor exit from the Tor Project's list, an iCloud Private Relay address and an AWS server. We've withheld the home and proxy addresses, since each is someone's home connection.
We asked: "Here's yesterday's signup export, signups.csv. Which accounts came from proxies or Tor?" Claude loaded the plugin's review-traffic skill, read the file, and looked up its 12 distinct addresses in one lookup_ips call. It answered:
Four of the 13 accounts came from proxies or Tor. Three (10485–10487) are on a residential proxy network and one (10490) is on a Tor node. Four more are flagged for other anonymization (2 VPN, 1 AWS hosting, 1 Apple Private Relay), and 5 are clean. Of the 13 signups, 4 came through a proxy or Tor, and 4 more came through a VPN, a hosting range or a privacy relay. The check had full coverage, so a "no" below means that category was checked and came back clean.
Proxies or Tor
user_id signup time (UTC) IP Category Provider Country / network 10485 sam.k.0412@example.net 13:41 (withheld) Residential proxy Novada Brazil, Jsm da Silva me (AS271124) 10486 sam.k.0413@example.net 13:42 (withheld) Residential proxy Novada Chile, Telefónica Chile (AS7418) 10487 sam.k.0414@example.net 13:44 (withheld) Residential proxy Novada Brazil, V tal (AS7738) 10490 noor.haddad@example.com 18:09 190.120.229.98 Tor exit node (also flagged as hosting, medium confidence) – Peru, Sondatech (AS263812) Other anonymization
user_id IP Category Provider Country / network 10482 k.osei@example.net 45.134.140.130 VPN and hosting Mullvad, on Datacamp US, Datacamp (AS212238) 10489 t.okafor@example.org 45.134.140.130 VPN and hosting Mullvad, on Datacamp US, Datacamp (AS212238) 10484 lena.fischer@example.com 172.224.236.1 Privacy relay Apple Private Relay US, Akamai (AS36183) 10491 build-bot@example.io 34.192.18.44 Hosting AWS US, Amazon (AS14618) Counts by category (records can be in more than one)
- Residential proxy: 3
- Tor: 1
- VPN: 2
- Hosting: 4
- Privacy relay: 1
- Mobile proxy, datacenter proxy, public proxy and CDN: 0 each
- Clean: 5 (10480, 10481, 10483, 10488 and 10492, all Comcast US home connections)
It went on to read the three sam.k accounts as probably one person: sequential email names, signed up within about 3 minutes, each on a different Novada address in Brazil or Chile. It said the two accounts behind one Mullvad exit, about 7¾ hours apart, aren't tied together by that alone, since Mullvad's exits are shared, that the Private Relay signup is usually an ordinary user with a privacy setting on, and that build-bot on AWS is probably automation. It closed by saying a flag shows the network is anonymized, not that the person is acting in bad faith, and offered the full joined table as a CSV.
The three sam.k accounts each came from a different address, in two countries. Checked one address at a time, they're three unrelated proxy hits; kept on their accounts, they're one burst. That's what the review-traffic skill adds, and since version 1.2.0 it gives each record's country and network from the same lookup. Private Relay is the one flag it said to weigh lightly, and our Private Relay post explains why it's rarely worth blocking at signup.
When your plan doesn't cover a field
Each lookup comes back with a coverage block: the fields the key's plan includes, the fields it doesn't, and a note that a missing field was never checked. With only ip and is_vpn covered, which is what a lookup without a key answers, the same question's answer opened with:
I can't tell you which accounts came from proxies or Tor. The lookup only checked for VPNs.
The API key's plan returns just
is_vpn. The Tor, residential, mobile, datacenter and public-proxy flags, plus hosting, relay, CDN, location and network data, were not checked. A missing flag doesn't mean an address is clean.
It still flagged the two accounts on the Mullvad server, and said the sam.k burst could be one person rotating proxies, which this lookup couldn't confirm. Where it guessed from its own knowledge that two addresses looked like a privacy relay and a cloud host, it said so and called it a guess, not a result. The note is in the tool's result, not only in the skill, so Claude reads it in claude.ai too. With every field covered, the first answer said the opposite: a "no" there meant the category "was checked and came back clean."
Your databases
The plugin also answers questions about the downloadable databases. Its database tools need a key with the db.download scope, which your organization's Default key has. We asked "Which databases are we licensed for, and how big is the latest VPN build?" Claude loaded the database-files skill, listed the catalog and answered:
Licensed databases: you hold three, all Open databases on the
standardlicense, which started 2026-10-20 and has no expiry date.
Family What it covers Version Formats tor_ipTor node IP ranges tor_ip_v1csvgz, mmdb relay_ipPrivacy relays (e.g. iCloud Private Relay) and enterprise web gateways (e.g. Zscaler) relay_ip_v1csvgz, mmdb relay_providerProvider catalog referenced by Relay IP relay_provider_v1csvgz Open databases are free under CC BY-SA 4.0. You have to credit VPNDetection and share anything you build from them under the same license. Every other family is
unlicensed, meaning it has never been bought. None areexpired.
Every organization holds those three from the start, a free one included: they were 3 of the 37 families the catalog listed. For the VPN build it read each database's metadata, which any key can read. VPN IP (vpn_ip_v1), built October 24, has 12,551,040 entries, 90.8 MB as csvgz and 79.2 MB as mmdb. VPN IP Extended's October 23 build has 13,290,002, at 99.6 MB and 130.3 MB.
Counting over a download
In Claude Code the analyze-database skill goes further: it downloads a copy with the vpndetection CLI, which checks the file's checksum, and counts over it locally with whatever you have, whether that's duckdb, sqlite or pandas. The Open databases make that a step any account can run. We asked "Download our Tor IP database and count its ranges by confidence, IPv4 and IPv6 separately." Claude read the Tor IP metadata, ran vpndetection db download tor_ip_v1, and, with no duckdb on our machine, wrote a short Python script to count the file:
I downloaded
tor_ip_v1(the Tor IP database, built 2026-10-24) and counted its ranges. The file was 108.5 KB and passed the SHA-256 check. The counts add up to the 13,218 rows the metadata reports.
Family Confidence Ranges IPv4 high 10,465 IPv4 medium 0 IPv6 high 2,590 IPv6 medium 163 IPv4 total 10,465 IPv6 total 2,753
We counted the same file ourselves and got the same numbers. The CLI has to be signed in first (vpndetection login); our run gave it a key in VPNDETECTION_API_KEY instead. Claude Code asks before each command it runs, and we'd allowed vpndetection and python3 ahead of time.
Other assistants
ChatGPT, Codex and any other MCP client connect to the same server: the MCP docs cover them, and our Claude page has the setup above. A free key adds the Tor fields and every paid plan the proxy fields, as our pricing page shows, and the API answers the same lookups from your own code.
