ip-enrichment-mcp

An MCP server that answers "what is this IP" from two independently-reported, honestly-labeled sources: a synced local copy of Azure service tags, and live reverse DNS. It never fabricates a hostname or a service tag - a source that didn't resolve reports null and its own status, and every answer says which source (if any) actually produced it, with a timestamp so staleness is visible.

A companion to grounded-kql-mcp, applying the same "grounded, not free-form" discipline to network identity resolution instead of KQL.

Quickstart (local, no Azure needed)

python -m venv .venv
.venv/Scripts/activate  # or source .venv/bin/activate on Linux/macOS
pip install -e ".[azure,dotenv,dev]"

python sync_service_tags.py --source fixture   # builds data/out/service_tags.sqlite
python smoke_test.py
python -m ipenrichmcp.server --transport stdio

Related MCP server: PeerGlass

The tools

resolve_ips(ips: list[str]) - up to 50 IPs per call. For each IP, returns:

{
  "ip": "13.68.163.33",
  "service_tag": {"name": "Storage.EastUS", "region": "eastus", "platform": "Azure", "matched_prefix": "13.68.163.32/28"},
  "service_tags_synced_at": "2026-09-11T12:00:00+00:00",
  "reverse_dns": null,
  "reverse_dns_status": "no_ptr_record"
}

list_service_tag_ranges(tag: str) - the reverse direction: given one exact Azure service-tag name, return every IPv4 CIDR prefix the synced local index has for it (e.g. "AzureAutomation.WestEurope", "Storage.EastUS", or the whole-cloud "AzureCloud"). Reads the same index resolve_ips uses; never re-fetches from Azure. A tag not present in the current sync comes back as found: false with an empty list - never a guessed or partial list standing in for "I don't know." A casing mismatch ("sql.westeurope" vs the real "Sql.WestEurope") is resolved and reported via case_insensitive_match, not silently matched to a possibly-different tag:

{
  "requested_tag": "AzureAutomation.WestEurope",
  "found": true,
  "tag_name": "AzureAutomation.WestEurope",
  "case_insensitive_match": false,
  "region": "westeurope",
  "platform": null,
  "address_prefixes": ["...", "..."],
  "prefix_count": 12,
  "service_tags_synced_at": "2026-09-11T12:00:00+00:00",
  "note": "ipv4_only - this index does not store IPv6 prefixes (see CLAUDE.md known gaps)"
}

Adjusting reserved-range handling for your environment

resolve_ips short-circuits IANA-reserved documentation/test ranges (RFC 5737 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, and RFC 3849 IPv6 2001:db8::/32) straight to a reserved_range status, with no network call and no cache write - these ranges can never have a real PTR answer by definition, so there's nothing to wait on.

That list is intentionally hardcoded, not config-driven (see CLAUDE.md D-003) - it's the well-known IANA set, not anything specific to a given deployment. If your own environment has other ranges that will predictably never resolve (a benchmarking block you use internally, a known black-holed segment), add them to _RESERVED_TEST_RANGES in src/ipenrichmcp/reverse_dns.py:

_RESERVED_TEST_RANGES = [
    ipaddress.ip_network("192.0.2.0/24"),
    ipaddress.ip_network("198.51.100.0/24"),
    ipaddress.ip_network("203.0.113.0/24"),
    ipaddress.ip_network("2001:db8::/32"),
    # add your own known-non-resolving ranges here, e.g.:
    # ipaddress.ip_network("198.18.0.0/15"),
]

Do not add RFC1918 private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) here - those routinely have real, meaningful internal PTR records, and short-circuiting them would silence a genuine answer, not skip a pointless one.

Two related constants in the same file are also worth knowing about if you're tuning this for your network:

• TIMEOUT_CACHE_TTL_SECONDS (default 5 min) - how long a timeout result is cached before being retried. Kept short deliberately, since a timeout means "we don't know," not a confirmed fact - see D-003.

• CACHE_TTL_SECONDS (default 24h) - how long a resolved/no_ptr_record answer is cached. These are resolver-confirmed facts, safe to trust longer.

Before escalating a private-name resolution failure

If resolve_ips can't resolve a private IP the way you expect, check these before opening a network ticket - most "the network is broken" reports turn out to be one of these instead:

1. Public or private? Public internet names resolve through the platform's default DNS with no special setup, on any host or PaaS compute, integrated into a VNet or not. If the failing name is a public FQDN, this list doesn't apply - that's a different kind of problem.

2. Is the compute actually on the network path to reach it? A private name only resolves if whatever's running this server has an actual route into the network that can answer for it. On Azure PaaS compute (Container Apps, App Service), that means VNet integration - without it, there is no path to a private resolver at all, not just a misconfigured one.

3. Does anything actually serve this name? "We have a private DNS zone" or "we have VNet integration" doesn't mean every private name is covered. An Azure Private DNS Zone linked to a VNet only answers for what's actually registered in it - PaaS auto-registration records, or A/PTR records someone created by hand. It has no knowledge of an on-prem or AD-integrated namespace unless something is explicitly forwarding for that domain suffix - an Azure DNS Private Resolver with conditional forwarding to the real on-prem servers, or a self-hosted DNS layer genuinely kept in sync with the on-prem upstream. Confirm the specific suffix you're querying is actually covered by one of these, not just that some private DNS infrastructure exists somewhere in the environment.

4. Test from the same network context as the deployment, not your laptop and not a jump box on a different subnet. A resolution that works from your machine and fails from the server's actual VNet/subnet is a real, specific difference worth handing to the network team - a resolution nobody has actually tried from that exact vantage point isn't evidence of anything yet.

5. Read the status the tool already gives you before assuming it's ambiguous. no_ptr_record proves the query reached a resolver and got an authoritative "nothing here" - connectivity and routing are fine, the record simply doesn't exist or isn't in scope. timeout proves nothing about which of those is true - it means no answer came back in time, and that's consistent with "resolver is slow," "resolver is unreachable," or "a firewall/NSG silently dropped the query" equally. Don't read a timeout as "the resolver is slow" - check reachability to the resolver itself before assuming that.

If you've checked 1-4 and it's still failing, that's a real network ticket - and one with much more to hand over than "DNS doesn't work": which specific name, which specific compute/VNet/subnet it's running from, and what a manual resolution test from that exact location actually showed.

Deploying to Azure

Terraform lives in infra/terraform/. Two things are prerequisites you bring yourself, not something this module creates for you:

• An existing Azure Container Apps Environment. This module deploys its Container App into an environment referenced via a data block (see data.tf) - it never creates one. If you don't already have one, create it first (a plain azurerm_container_app_environment resource, the CLI, or the Portal), then point container_app_environment_name / container_app_environment_resource_group_name at it.

• A resource group for the new resources this module does create (ACR, a managed identity, the Container App itself).

• A Storage Account for Terraform's remote state (decision D-011, recorded in the author's own local working notes - internal/decisions.md is gitignored, not part of this repo, so that's not a citation you can open; the reasoning that matters is inline here and in CLAUDE.md). Local .tfstate isn't enough once anything other than your own machine needs to run terraform apply - a CI runner in particular starts with no state at all. Create (or reuse) a Storage Account and a blob container for it yourself; this module doesn't manage its own backend, for the same chicken-and-egg reason it doesn't create its own Container Apps Environment.

None of these three has a default in variables.tf or versions.tf - there's nothing generic a shared repo could guess about your own subscription, so all three are required. Copy terraform.tfvars.example to terraform.tfvars, and backend.hcl.example to backend.hcl (both gitignored, never commit the real ones), fill in your own values, then deploy by hand - for this repo that is the fallback path, for when the pipeline below itself needs debugging, not the normal way to ship:

az acr build --registry <your-acr-name> --image ipenrichmcp:<a-tag> .
terraform -chdir=infra/terraform init -backend-config=backend.hcl
terraform -chdir=infra/terraform apply -var image_tag=<the-same-tag>

Authentication to the state backend is via Azure AD (use_azuread_auth = true), not a storage account key - your own az login session locally, the CI managed identity's federated credential in a pipeline. Either way, whatever identity is running terraform needs Storage Blob Data Contributor on that container specifically - a role assignment scoped to your app's resource group does not reach a state storage account that lives elsewhere.

CI/CD (GitHub Actions)

This repo's own deployment runs through GitHub Actions rather than manual terraform apply calls, authenticating to Azure via OIDC (a federated identity credential on a user-assigned managed identity), not a stored client secret - no long-lived Azure credential exists in GitHub at all. Every build gets tagged with the git commit sha it was built from and nothing else

• :latest is deliberately not used as a deploy target (a mutable tag plus a scale-to-zero app made a deploy's timing accidental rather than controlled; decision D-007, same caveat as above - the author's own local notes, not something in this repo). The workflow is .github/workflows/deploy.yml:

• Push to master runs build-and-plan automatically: builds and pushes ipenrichmcp:<sha> (skipped if that tag already exists, so a re-run never re-pushes an existing tag with a different digest), then a read-only terraform plan, summarized on the run page. Nothing is deployed.

• "Run workflow" in the Actions tab (workflow_dispatch, master only) runs the same build-and-plan and then apply: a fresh plan and terraform apply in one job, followed by live verification - Azure must report the Container App on this build's sha tag with its newest revision ready, and verify_deployment.py calls both tools through a real MCP client against the live endpoint, asserting on content (a real Azure IP gets a service tag whose matched_prefix actually contains it, AzureCloud has prefixes, and service_tags_synced_at is newer than the apply - i.e. the answer came from a container started by this deploy). A green run means verified, not just applied.

That manual trigger is the approval gate - a human still signs off on every production change; the pipeline automates the mechanics around that gate, not the gate itself. (GitHub's native Environment "required reviewers" protection needs a paid plan for a private repo, so this repo uses a manual trigger instead - decision D-013, if you're wondering why it's not a green approval banner; again, the full writeup is the author's own local notes, not something this repo carries.) The plan file is never uploaded as an artifact between jobs: a saved Terraform plan contains sensitive values (the API key) in plaintext.

verify_deployment.py also works by hand against any deployment: IPENRICHMCP_API_KEY=... python verify_deployment.py https://<fqdn>/mcp.

Setting this up for your own fork means creating your own dedicated managed identity and federated credential (documented, not automated by this repo - identity/credential setup is a decision only you should make for your own subscription), granting it both roles it needs (Contributor on your app resource group, and Storage Blob Data Contributor on your state container - two separate scopes, easy to grant the first and forget the second), and populating your fork's own GitHub Secrets (the API key) and Variables (client ID, tenant ID, subscription ID, and the resource-group/environment/backend names above) accordingly - all scoped to a GitHub Environment named production, which both jobs declare. The manual az acr build + terraform apply commands above still work unchanged if you'd rather deploy by hand instead.

See CLAUDE.md for the full design and the standing invariants this repo does not relax. Remaining known gaps: the service-tags index is IPv4-only by design, so an IPv6 input gets the reverse-DNS side only and always reports service_tag: null (correctly null, never fabricated - the earlier bug where an IPv6 address raised out of resolve_ips and killed the whole batch is fixed, see D-002); and there is no scheduled sync - sync_service_tags.py is run explicitly, with the server warning at startup if the local index is stale. Reverse DNS resolution also depends entirely on whatever resolver the host or platform this server runs on is configured with - the server has no DNS configuration of its own, by design, since reverse_dns.py goes through the system resolver via the stdlib socket.gethostbyaddr() (see that module's docstring).