Skip to main content
Glama

fleet-geo — an MCP that answers "where does this model actually run?"

test

A zero-dependency MCP server (stdio, Node >= 20) that resolves the physical location of inference for each model in the Orca fleet, and refuses to guess.

Written because a prompt rots: providers change, endpoints move, new lanes appear. A tool that re-derives the answer from live data does not.

fleet-geo-mcp/
  server.mjs              MCP stdio transport + 10 tools
  src/observe.mjs         observe_endpoints: proxy, OS socket table, strace SNI/DNS (no decryption)
  src/doh.mjs             DNS over HTTPS (ISP-independent evidence)
  src/sources.mjs         Cymru ASN, RDAP, AWS/GCP prefix tables, PeeringDB, crt.sh, globalping, headers
  src/geo.mjs             CIDR math, distance, RTT floor, region anchors, hostname fingerprints
  src/classify.mjs        evidence -> four planes -> confidence + contradictions
  src/catalog.mjs         the only hand-maintained data, plus record_fact
  catalog.json            provider seeds, all marked hypothesis until cited
  fleet.json              the lane table (W1-W7, C, B, T) - adding a lane is a one-line edit
  config.json             entitled-host allowlist + limits
  test/selftest.mjs       41 checks (offline strict, online tolerant)
  test/observe.test.mjs   11 observe_endpoints checks, offline on every OS
  test/stdio-check.mjs    protocol surface, replayed from a recorded session
  dsh-bundle/             the DSH wrapper, shipped with the server

Runs on every OS

Windows, macOS and Linux, on Node.js 20 or newer, with zero dependencies. Every tool uses only Node built-ins and public HTTPS/DNS sources, so it behaves the same on all three. The only OS-specific part is observe_endpoints, which picks the native tool for each OS and never needs root or admin rights:

Windows

macOS

Linux

all lookup tools (locate_model, fleet_status, ...)

yes

yes

yes

observe_endpoints proxy layer

yes

yes

yes

observe_endpoints socket table

netstat -ano + PowerShell process tree

lsof + ps

ss + ps

observe_endpoints SNI/DNS names

via the proxy

via the proxy

proxy + strace (if installed)

CLI shims (codex.cmd etc.)

run through the shell

direct

direct

process cleanup on timeout

taskkill /T /F

process group

process group

Per-OS differences in how a lane is launched live in fleet.json as observe.argvByPlatform (for example agy needs a pseudo-TTY via script on Linux and macOS). Shell examples below are PowerShell; the same commands work unchanged in bash or zsh.

Related MCP server: Proof Mode

The one idea

Four planes, never merged.

Plane

What it is

Why it matters

CONTROL

the base URL the CLI actually calls

may be a router, not the model author

EDGE

where TLS terminates

nearest to you; almost never the model

ORIGIN

where weights execute

this is the answer

LEGAL

entity + residency commitment

what a DPO accepts; constrains origin

Every naive geolocation answer collapses these into one and reports the Cloudflare PoP down the street as "the datacenter".

Tools

Tool

Use

locate_model

one lane: model / lane name / base_url -> full location card

fleet_status

every lane in one sweep -> table + roll-up

trace_endpoint

one hostname -> CNAME hops, ASN, cloud region, RDAP

lookup_prefix

one IP -> ASN, published cloud region, PeeringDB facilities

find_regional_endpoints

crt.sh subdomains, regional ones surfaced

probe_latency

distributed probes + the RTT floor falsifier

inspect_edge

headers from an entitled endpoint -> edge PoP only

record_fact

cite a provider page with a quote -> tier-A anchor

observe_endpoints

run a lane's one-line probe and record the hosts and IPs it really connects to

explain_rules

precedence, planes, confidence, falsifier

observe_endpoints

Config files say what a CLI should call; this records what it does call. Each lane in fleet.json carries an observe.argv (with optional argvByPlatform and a git fixture for jev). With run:true the tool runs that one prompt and watches it through three layers:

Layer

Linux

macOS

Windows

Sees

logging CONNECT proxy (HTTPS_PROXY)

yes

yes

yes

hostname, port, bytes per tunnel

OS socket table for the process tree

ss

lsof

netstat -ano

every remote IP, proxy or not

strace -yy, when installed

yes

-

-

TLS SNI hostname, DNS questions, every connect

Nothing is decrypted: the hostname comes from the CONNECT line, the cleartext SNI or the DNS question. Every destination IP then gets lookup_prefix-style facts and an EDGE / ENDPOINT label. The result is CONTROL-plane evidence, saved under observations/. It ends at the TLS edge and never proves the origin. Without run:true it only prints the commands, because each lane costs one model call.

The answer shape

{
  "planes": { "control": {...}, "edge": {...}, "origin": {...}, "legal": {...} },
  "location": { "country": "KR", "region": "ap-northeast-2", "facility": null,
                "precision": "region" },   // facility > metro > region > country > unknown
  "confidence": "ANCHORED",               // ANCHORED | CORROBORATED | INDICATED | OPEN
  "confidenceWhy": "1 tier-A anchor(s): cloud-published-region",
  "contradictions": [],                   // e.g. an RTT below the fiber floor
  "evidence": [ { "id": "E2", "tier": "A", "source": "aws ip-ranges.json",
                  "observed": "3.5.140.1 falls in 3.5.140.0/22, published as AWS region ap-northeast-2" } ],
  "nextProbes": ["Region is anchored. A facility needs documentary evidence: ..."]
}

precision is the honest word for "exact". A tool that returns a street address for a Cloudflare-fronted API is lying; one that returns region: ap-northeast-2, precision: region, confidence: ANCHORED is not.

Precedence (highest first)

  1. provider documentation (cited via record_fact) / region encoded in the hostname

  2. the cloud's own published prefix table (AWS ip-ranges.json, gstatic cloud.json)

  3. PeeringDB facility for the serving ASN

  4. RDAP / ASN registration

  5. commercial geoIP databases

  6. latency inference

Rule 2 is the sharpest trick: when an address falls inside a published AWS or GCP prefix, the cloud itself tells you which region owns it. That beats every geoIP product, and it costs nothing.

The falsifier

Fiber runs at ~200,000 km/s, so a round trip costs ~1 ms per 100 km of path. Real paths are longer than the great circle, so measured RTT normally sits above the floor. A measurement far below it is physically impossible — and therefore a hard test:

// probe_latency from Helsinki @1.4 ms, claimed origin Ashburn (7000 km)
{ "verdict": "FALSIFIED",
  "rows": [{ "impliedMaxDistanceKm": 140, "distanceToClaimedOriginKm": 7000,
             "floorMs": 70, "violation": { "floorMs": 70, "hardFloorMs": 53 } }] }

It can only ever disprove a claim. That is exactly what a confident answer needs.

Guardrails in code, not just in prose

  • Entitlement gate. inspect_edge refuses any host absent from config.json entitledHosts. Passive lookups stay open; traffic does not.

  • Pacing. Per-source minimum intervals. These are free shared services.

  • Secret hygiene. Auth headers are stripped before they can be echoed.

  • Provenance gate. record_fact rejects a fact without an http(s) URL and a >=12 char verbatim quote. An agent cannot promote its own guess to a fact.

  • No invasive technique. DNS, RDAP, published tables, PeeringDB, crt.sh, ICMP from a third-party probe network. No port scanning, no whois TCP/43, no auth walls.

Dynamic by construction

Nothing about a provider is hardcoded except what only a human can supply: who publishes the model, and what their documentation claims.

  • New endpoint? trace_endpoint resolves it now.

  • New provider? record_fact with publisher + match[] adds it.

  • Provider moves? Live DNS and published ranges follow; the card changes.

  • Documentation ages? Every fact carries verified_at; staleness() flags anything past staleAfterDays (90) and prints "never verified" for the rest.

Honest limits

  1. For CDN-fronted APIs the origin is not externally observable — the card returns OPEN plus the exact probe that would settle it.

  2. Azure publishes no queryable service-tag JSON any more, so Azure region comes from the resource itself (az cognitiveservices account show ... --location); the tool says so rather than guessing.

  3. Passthrough aggregators (OpenRouter, Together, Fireworks) return a provider field per response. That is authoritative for the serving entity; the tool names it as the next probe instead of inventing it.

  4. IPv6 addresses skip the ASN lookup in v1 (IPv4 only); observe_endpoints labels them UNKNOWN rather than presuming they are unicast endpoints.

  5. observe_endpoints sees where a CLI connects, which ends at the TLS edge. A CLI that hands traffic to a local gateway outside its process tree is reported as LOCAL_GATEWAY with the loopback ports, not as a location.

Develop

cd C:\DEV\fleet-geo-mcp
node server.mjs --selftest        # 41 checks; offline strict, network tolerant
node test/observe.test.mjs        # 11 observe_endpoints checks (or: npm test for both)
node server.mjs --tool observe_endpoints --args '{"lane":"all"}'            # plan only
node server.mjs --tool observe_endpoints --args '{"lane":"W7","run":true}'  # one model call
node server.mjs --list-tools
node server.mjs --tool fleet_status --args '{"limit":3}'
node server.mjs --tool locate_model --args '{"lane":"W7"}'

# full stdio session (shell redirection, not a piped child process)
cmd /c "node server.mjs < test\fixtures\stdio-requests.jsonl > test\fixtures\stdio-responses.jsonl"
node test/stdio-check.mjs

Companion

docs/PROMPT.md is the analyst prompt this server replaced: a static spec that rots the moment a provider changes. Kept as the design rationale - the four planes, the evidence ladder, the falsification pass - for when the tool's output needs arguing in prose.

Install

Two routes - a DSH bundle or a single patch row - both in INSTALL.md. Placeholders there map to $env:DSH_NODE_EXECUTABLE, %USERPROFILE%\.dsh\profiles\<profile>, and this checkout.

License

MIT - see LICENSE.

Available Tools

10 tools
explain_rulesExplain the rulesA

Return the source precedence, plane definitions, confidence states and the RTT falsifier used by every other tool.

Inputs: no named parameters.

find_regional_endpointsFind regional endpointsA

Search certificate transparency logs for subdomains of a domain and surface ones that look regional (-eu, -jp, -sg, -cn ...). Providers often run regional endpoints that no documentation mentions.

Inputs: domain (required), limit.

fleet_statusWhole-fleet location sweepA

Run locate_model across every catalog provider that has a known API host and return one summary table: publisher, serving entity, edge operator, country/region, precision and confidence per lane. The one call to re-run whenever the fleet or a provider changes.

Inputs: deep, lanes, limit.

inspect_edgeInspect edge headersA

Read response headers from an ENTITLED endpoint only (config.json allowlist) and report the TLS-terminating PoP. Explicitly an edge-plane fact: it never establishes where inference ran.

Inputs: url (required).

locate_modelLocate a modelA

Resolve where a model's inference physically runs. Accepts a model id, a fleet lane/CLI name, or an explicit base_url. Returns a four-plane location card (control/edge/origin/legal), the serving chain, evidence rows with sources, a confidence state, contradictions, and the next probe that would tighten the answer. Re-derives everything from live DNS, ASN, cloud prefix tables and PeeringDB, so it tracks provider changes without redeploying.

Inputs: lane, model, base_url.

lookup_prefixLook up an IPB

Identify a single address: ASN and org, the cloud's own published region for the prefix, RDAP registration, and PeeringDB facilities. The published cloud region outranks any geoIP database.

Inputs: ip (required), include_facilities.

observe_endpointsObserve which hosts a lane really callsA

Run a lane's one-line probe prompt (fleet.json observe.argv) and record every outbound connection: a logging CONNECT proxy (every OS), the OS socket table for the process tree (ss / lsof / netstat), and on Linux strace for TLS SNI and DNS names. Nothing is decrypted. Settles the CONTROL plane only - observed hosts end at the TLS edge, never the inference origin. Spends one model call per lane, so it only runs with run:true; without it, it returns the commands it would run.

Inputs: lane (required), run, locate, timeout_s.

probe_latencyProbe latency and test the RTT floorB

Measure a host from distributed vantage points and test the physical RTT floor. Returns per-probe implied maximum distance, an anycast verdict, and a FALSIFIED verdict when a measurement is impossible for the claimed origin.

Inputs: host (required), limit, expected_region, expected_country, +1 more.

record_factRecord a documented factA

Add a provider residency or facility fact to the catalog, citing a source URL and a verbatim quote. This is how the catalog learns: a verified fact becomes a tier-A anchor and lifts the matching card to ANCHORED. Pass publisher + match[] to add a provider that is not in the catalog yet.

Inputs: kind (required), quote (required), provider (required), source_url (required), +8 more.

trace_endpointTrace an endpointA

Resolve one hostname into a serving chain: CNAME hops, addresses, ASN and org, registry RDAP, and the published cloud region of each address. Flags CDN/anycast addresses so an edge PoP is never mistaken for an origin.

Inputs: host (required), max_ips.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools target clearly different objects: locate_model (model→location card), trace_endpoint (hostname→serving chain), lookup_prefix (IP→ASN/region), fleet_status (batch roll-up). The closest pairs are trace_endpoint vs lookup_prefix (hostname vs address, both emitting ASN/RDAP/cloud region) and inspect_edge vs observe_endpoints (both probes, different planes), but the descriptions explicitly disambiguate by input type and plane.

    Naming Consistency4/5

    All names are snake_case and almost all follow verb_noun (inspect_edge, record_fact, probe_latency, locate_model, trace_endpoint, lookup_prefix, explain_rules). The one deviation is fleet_status, a noun-only name, which breaks the pattern slightly but remains readable in context.

    Tool Count5/5

    Ten tools is well within the sweet spot and each maps to a distinct investigation step (edge, control, origin, legal, catalog write, discovery, falsification, meta). No tool feels redundant filler, and none of the planes is served by more than one or two tools.

    Completeness4/5

    Coverage is strong across the four planes: inspect_edge (edge), observe_endpoints (control), trace_endpoint/lookup_prefix/locate_model (origin), record_fact (catalog write), plus fleet_status and explain_rules. The notable gap is the catalog read/delete side — record_fact writes facts but there is no tool to list, inspect, or retract a fact, so bad entries cannot be corrected without re-recording.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for achieving peak inference performance by detecting drift between code and runtime behavior, comparing against benchmarks, and providing optimization templates.
      8
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server implementing a multi-phase backend for structured model interactions, bounded compilation, exact-hash confirmation, and Codex-run provenance, with trust-separation hardening.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      This MCP server provides a stateful, resettable, verifiable API runtime that gates every tool call, enabling agents to run long workflows against provider-shaped environments without live provider write access. It records decisions, side effects, and outcome evidence for replayable, verifiable benchmark runs.
      Apache 2.0