.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/fcc-broadband-mcp-server</h1> <p><b>Access FCC broadband availability, coverage analysis, and digital divide data for US geographies and census blocks via MCP. STDIO or Streamable HTTP.</b> <div>9 Tools • 2 Resources • 1 Prompt</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://fcc-broadband.caseyjhand.com/mcp

</div>

Tools

9 tools for working with FCC broadband data — block-level availability, geography-level coverage analysis, provider search, and BDC bulk download manifests:

fcc_geocode_block

Convert geographic coordinates to a census block FIPS code for broadband availability lookups.

• Calls the FCC Geo API — no auth required, no rate limit documented
• Returns 15-digit block FIPS, 5-digit county FIPS, county name, state FIPS, 2-letter state code, and state name
• Required first step before fcc_search_availability — the broadband deployment dataset is indexed by census block, not address

fcc_search_availability

Query which ISPs serve a specific census block and what speeds they advertise.

• Requires a 15-digit census block FIPS; use fcc_geocode_block to convert coordinates first
• Filter by technology code (fiber=50, cable=40–43, DSL=10–12, satellite=60, fixed wireless=70)
• Filter by minimum advertised download speed in Mbps
• Filter to consumer-only or business-only service
• Returns per-provider records with hoconum, techcode, maxaddown, maxadup, consumer, business
• Coverage is Form 477 data through June 2021 — reflects ISP-reported availability at census block granularity (not address-level)

fcc_get_coverage_summary

Analyze broadband access across any US geography at a given speed threshold.

• Supports seven geography types: nation, state, county, cd (congressional district), place (census-designated place), cbsa (metro area), tribal
• Technology filter: any wired/fixed wireless (acfosw), fiber only (f), cable (c), DSL (a), satellite (s), fixed wireless (w), or combinations
• Speed thresholds: 0.2, 4, 10, 25 (FCC legacy broadband definition), 100 (BEAD standard), 250, 1000 Mbps
• Returns population breakdowns: zero providers (unserved), one (no competition), two, three-plus; coverage %, unserved %, competitive %
• Per-segment breakdown by urban/rural and tribal/non-tribal for equity analysis

fcc_compare_areas

Rank geographies by broadband access metrics to identify where underservice is worst.

• Compare up to 50 geographies of the same type, or all 50 states + DC via compare_all_states: true
• Sort by unserved population share, raw unserved headcount (useful for BEAD funding allocation), coverage rate, or competitive share
• Returns a ranked table with per-geography population and coverage metrics

fcc_find_underserved

Find the most broadband-underserved areas within a state or nationwide.

• Scope to a specific state or run nationwide (returns top areas only)
• Geography granularity: county, congressional district, census place, or CBSA
• Default filter: rural areas only — where underservice is most concentrated
• Minimum unserved population threshold to exclude very small areas
• Results ranked by unserved population percentage

fcc_search_providers

Look up ISPs by name or state to get hoconum identifiers for follow-up queries.

• Case-insensitive partial name match — e.g., "Comcast", "T-Mobile", "Frontier"
• Filter by 2-letter state abbreviation or technology code
• Returns deduplicated holding companies with hoconum, states served, and technology codes
• Geographic filtering is state-level; sub-state granularity requires cross-referencing block data via fcc_search_availability
• Up to 200 results per call

fcc_list_filing_periods

Discover valid data vintages before querying download manifests.

• Form 477 periods (Jun 2015–Jun 2021) are hardcoded — always available, no credentials needed
• BDC as-of dates (Jun 2022 onward) are fetched live from the authenticated API — requires FCC_BDC_USERNAME and FCC_BDC_HASH_VALUE
• Call before fcc_list_downloads to determine valid as_of_date values

fcc_list_downloads

List BDC bulk data files available for download for a specific filing period.

• Requires BDC API credentials (FCC_BDC_USERNAME, FCC_BDC_HASH_VALUE)
• Filter by data type (availability or challenge), file category, technology type, state, or provider name
• Returns file metadata — provider, state, technology, record count — plus download URLs
• Returns file manifests, not file contents; BDC CSVs are large zipped files not suitable for inline API response

Resources and prompts

All resource data is also reachable via tools. The providers/list resource is derived from the deployment table via $group aggregation — use fcc_search_providers for filtered lookups.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

FCC broadband-specific:

• Wraps three FCC data sources: Form 477 public data via Socrata (no auth, 2015–2021), BDC Public Data API (authenticated, Jun 2022 onward), and FCC Geo API (no auth)
• Auth-optional design — BDC tools return a structured credentials_required error with setup instructions when credentials are absent; all Form 477 and geocoding tools always work without credentials
• Area Table aggregation for equity analysis — uses the pre-aggregated geography table (xvwq-qtaj) instead of querying the 50M-row deployment table, enabling fast coverage analysis at county and state scale
• All data is US federal government public domain (17 USC §105) — safe to distribute and cache

Agent-friendly output:

• Structured error contracts on every tool — typed error codes (block_not_found, credentials_required, geography_not_found, invalid_as_of_date) with actionable next-step hints so agents can recover without parsing text
• Per-segment breakdowns in coverage tools — urban/rural and tribal/non-tribal split in fcc_get_coverage_summary outputs so agents can target equity analysis without additional queries
• Two-era data coverage bridged transparently — Form 477 (2015–2021) and BDC (2022–present) exposed through a unified tool surface, with data ceiling documented in tool descriptions so agents can surface limitations accurately

Getting started

Public Hosted Instance

A public instance is available at https://fcc-broadband.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "fcc-broadband-mcp-server": {
      "type": "streamable-http",
      "url": "https://fcc-broadband.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "fcc-broadband-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fcc-broadband-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "fcc-broadband-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/fcc-broadband-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• Optional: FCC BDC credentials for fcc_list_downloads and BDC filing periods. Generate a token at broadbandmap.fcc.gov under "Manage API Access" — no OAuth, manual token generation only.
• Optional: Socrata app token (FCC_OPENDATA_APP_TOKEN) for higher rate limits on Form 477 queries.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/fcc-broadband-mcp-server.git

1. Navigate into the directory:

cd fcc-broadband-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env and set required vars

Configuration

All configuration is validated at startup via Zod schemas in src/config/. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t fcc-broadband-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 fcc-broadband-mcp-server

The Dockerfile defaults to HTTP transport and stateless session mode, logging to /var/log/fcc-broadband-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
• Socrata returns all numeric fields as strings — parse has_0, has_1, has_2, has_3more, maxaddown, maxadup as integers

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.