MCP Server

The Whitepages MCP (Model Context Protocol) server allows AI assistants like Claude Desktop, Cursor, and other MCP-compatible tools to directly access Whitepages API functionality.

Quick Start

Get Your API Key

If you don't have an API key yet, get a trial key.

Configure Your AI Tool

Choose your AI tool below and copy the configuration.

Configuration

Claude Desktop does not support custom headers directly for remote MCP servers. Use mcp-remote as a bridge to handle authentication.

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "whitepages": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.whitepages.com/mcp",
        "--header",
        "x-api-key: ${WHITEPAGES_API_KEY}"
      ],
      "env": {
        "WHITEPAGES_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual Whitepages API key.

After saving, restart Claude Desktop for the changes to take effect.

Add the MCP server using the CLI or edit your configuration file directly.

Using CLI:

claude mcp add whitepages --scope user

Or edit ~/.claude.json (macOS/Linux) or %USERPROFILE%\.claude.json (Windows):

{
  "mcpServers": {
    "whitepages": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.whitepages.com/mcp",
        "--header",
        "x-api-key: ${WHITEPAGES_API_KEY}"
      ],
      "env": {
        "WHITEPAGES_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual Whitepages API key.

Restart Claude Code after updating the configuration.

Add this to your Cursor MCP settings file:

macOS/Linux: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "whitepages": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.whitepages.com/mcp",
        "--header",
        "x-api-key: ${WHITEPAGES_API_KEY}"
      ],
      "env": {
        "WHITEPAGES_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Restart Cursor after updating the configuration.

Cline supports custom headers directly for remote MCP servers.

In VS Code with Cline extension:

Click the MCP Servers icon in the Cline panel
Select the Configure tab
Click "Edit MCP Settings" to open cline_mcp_settings.json
Add this configuration:

{
  "mcpServers": {
    "whitepages": {
      "url": "https://api.whitepages.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

OpenCode supports custom headers directly for remote MCP servers.

Add this to your opencode.json configuration:

{
  "mcp": {
    "whitepages": {
      "type": "remote",
      "url": "https://api.whitepages.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY_HERE"
      },
      "enabled": true
    }
  }
}

Zed currently focuses on stdio-based MCP servers. Use mcp-remote to connect to remote servers.

Add this to your Zed settings (~/.config/zed/settings.json or via Zed → Settings):

{
  "context_servers": {
    "whitepages": {
      "command": {
        "path": "npx",
        "args": [
          "mcp-remote",
          "https://api.whitepages.com/mcp",
          "--header",
          "x-api-key: YOUR_API_KEY_HERE"
        ]
      }
    }
  }
}

Zed's remote MCP support is still evolving. Check the Zed MCP documentation for the latest configuration format.

While Postman doesn't directly support MCP, you can test the underlying API:

Create a new request
Set method to POST
Set URL to https://api.whitepages.com/mcp
Add headers:
- Content-Type: application/json
- Accept: text/event-stream
- x-api-key: YOUR_API_KEY_HERE
Set body (raw JSON):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "postman-test",
      "version": "1.0.0"
    }
  }
}

Note: Postman may have limitations with Server-Sent Events (SSE) responses. For full MCP testing, use the MCP Inspector instead.

The MCP Inspector is the official tool for testing MCP servers:

Install and run:

npx @modelcontextprotocol/inspector https://api.whitepages.com/mcp

In the Inspector UI:
- Transport Type: SSE
- URL: https://api.whitepages.com/mcp
- Click Authentication button
- Add header: x-api-key = YOUR_API_KEY_HERE
- Click Connect
Once connected, you can explore available tools and test them interactively.

Authentication

All requests to the Whitepages MCP server require authentication via the x-api-key header:

x-api-key: YOUR_API_KEY_HERE

If you don't have an API key:

Get a trial key for testing
Purchase a plan for production use

Available Tools

Each API endpoint is accessible through the MCP server as a tool. The available tools and their parameters will be shown in your AI assistant after connecting.

Usage in AI Assistants

After configuring the MCP server, you can ask your AI assistant to use Whitepages data:

Example prompts:

"Find contact information for John Smith in Seattle"
"Look up who owns the phone number 206-555-0100"
"Get details about the property at 123 Main St, Seattle, WA"

Your AI assistant will automatically use the appropriate Whitepages MCP tools to fulfill these requests.

MCP requests are billed identically to direct API calls. Each tool invocation through the MCP server consumes credits from your subscription plan at the same rate as if you called the REST API directly.

For example:

A person search via MCP = same cost as a person search via REST API
A reverse phone lookup via MCP = same cost as a reverse phone lookup via REST API

See Billing for detailed pricing information.

Troubleshooting

Connection Failed: Verify your API key is correct and has active credits.

Rate Limits: MCP requests count against your API rate limits. Monitor your usage in the dashboard.

If you encounter issues:

Check that your API key is valid and has credits
Verify the server URL is correct: https://api.whitepages.com/mcp
Ensure the x-api-key header is properly configured
Restart your AI tool after configuration changes

On this page