@freeconnect/mcp

MCP server that checks ISP availability at any US address. Give it a street address, get back which internet providers serve that location.

Quick start

For developers

To test the MCP tools and results you can use the MPC Inspector. No need to clone the repo. Just run this commands in a terminal.

npx @modelcontextprotocol/inspector \ npx --yes @freeconnect/mcp@latest

Make sure you add these env variables in the MCP Inspector UI. ALL 3 ARE REQUIRED

RV_SERVICEABILITY_URL: '...',
RV_SERVICEABILITY_KEY: '...',
RV_TENANT: 'freeconnect-mcp',

After that you can explore the Tool Calling and the responses

For AI Dekstop Clients

No installation required. Add this to your MCP client config and you're done.

Claude Code / Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "serviceability": {
      "command": "npx",
      "args": ["-y", "@freeconnect/mcp"],
      "env": {
        "RV_SERVICEABILITY_URL": "your-api-url",
        "RV_SERVICEABILITY_KEY": "your-api-key",
        "RV_TENANT": "freeconnect-mcp"
      }
    }
  }
}

Restart your MCP client. check_serviceability is ready to use.

Cursor — same JSON, added under mcpServers in Cursor settings.

Other clients — any MCP-compatible client works. The server speaks stdio and runs via npx.

Credentials

Contact FreeConnect to get your RV_SERVICEABILITY_URL and RV_SERVICEABILITY_KEY. Set RV_TENANT to freeconnect-mcp or easyconnect-mcp depending on which product you're building for.

Tool reference

check_serviceability

Input:

| Field | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------------------- | | street | string | yes | Street address line 1 (e.g. "123 Main St") | | city | string | yes | City name | | state | string | yes | 2-letter state abbreviation (e.g. "CA") | | zip | string | yes | 5-digit ZIP code | | secondary | string | no | Apt, unit, or suite (e.g. "Apt 4B") |

The AI model handles address parsing from natural language — no pre-formatting needed.

Output:

{
  "serviceability_id": "abc123",
  "top_provider": "spectrum",
  "providers": ["spectrum", "att"],
  "primary_provider_count": 2,
  "satellite_provider_count": 1,
  "frontier_fiber_top": false,
  "lumen_serviceable": true,
  "lumen_metadata": {},
  "offers": {},
  "timed_out": false
}

| Field | Description | | -------------------------- | --------------------------------------------------------- | | serviceability_id | Redventure session ID for this check | | top_provider | Provider with best coverage at the address | | providers | All providers with coverage (includes satellite) | | primary_provider_count | Non-satellite provider count | | satellite_provider_count | Satellite-only providers (Viasat, HughesNet, etc.) | | frontier_fiber_top | true when Frontier Fiber (not copper) is the top option | | lumen_serviceable | Whether Lumen confirmed the address is serviceable | | offers | Offer IDs keyed by provider slug | | timed_out | true if the 35s timeout fired — result is partial |

How it works

Two-phase polling flow against our internal serviceability API:

check_serviceability called
  │
  ├─ POST /serviceability/form          → serviceability API returns a session PK
  │
  └─ Poll /serviceability/poll/results  → every 10s, up to 10 retries
       └─ Stops when API returns a confirmed result
            └─ Returns providers, top provider, offers, metadata

Total timeout is 35 seconds. On timeout the server returns whatever partial data Redventure returned in the initial call, with timed_out: true.

Environment variables

| Variable | Required | Description | | ----------------------- | -------- | ---------------------------------------------------------------- | | RV_SERVICEABILITY_URL | yes | Redventure API base URL | | RV_SERVICEABILITY_KEY | yes | API key (sent as x-api-key) | | RV_TENANT | yes | freeconnect-mcp or easyconnect-mcp (sent as Authorization) |

For Mazama developers

Inside the monorepo, the server also accepts the webform's existing env var names (VITE_RV_SERVICEABILITY_API, VITE_RV_SERVICEABILITY_KEY, VITE_TENANT) as a fallback — so no extra config if apps/form/.env.local is already filled in.

# Dev (tsx, no build step)
cd packages/mcp
pnpm dev

# Build
pnpm build

# Publish to npm
npm publish --access public

# Publish to MCP Registry (one-time setup)
brew install mcp-publisher
mcp-publisher login github
mcp-publisher publish

Custom Node.js agent

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@freeconnect/mcp'],
  env: {
    RV_SERVICEABILITY_URL: '...',
    RV_SERVICEABILITY_KEY: '...',
    RV_TENANT: 'freeconnect-mcp',
  },
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({
  name: 'check_serviceability',
  arguments: { street: '123 Main St', city: 'Los Angeles', state: 'CA', zip: '90001' },
});