Quickstart

This guide walks you through connecting the FullContact MCP Server to the most common AI clients. The setup is the same in spirit across every client: point the client at the MCP Server endpoint and supply your FullContact API key as a Bearer token.

If you don't yet have a key, generate one at docs.fullcontact.com/docs/generate-an-api-key before continuing.

📘
All clients require an API key
The MCP Server reuses your existing FullContact API key for authentication. There is no separate MCP credential to provision. Every example below assumes you have set the environment variable FULLCONTACT_API_KEY to your key, and we recommend using a secrets manager or .env rather than hard-coding the value.

The hosted MCP Server endpoint is:

https://api.fullcontact.com/v3/mcp

Claude Desktop

Claude Desktop loads MCP servers from claude_desktop_config.json. The server runs as a subprocess of the desktop app, so the config has to give it everything it needs to launch on its own — no shell environment, no PATH inheritance.

📘
Before you start
You need Node.js installed locally so that npx can fetch the mcp-remote bridge. Install Node from nodejs.org or via Homebrew (brew install node) before continuing. Confirm with which npx in a terminal — you'll need that absolute path in step 2.

1. Open the config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it with {} as the contents. If it does exist, merge the mcpServers block below into it — don't overwrite any existing keys (e.g. preferences).

🔒
macOS Finder tip
The Library folder is hidden by default. In Finder, hold Option while clicking the Go menu — Library will appear in the list. Or press ⌘⇧G and paste ~/Library/Application Support/Claude.

2. Add the FullContact MCP Server entry.

{
  "mcpServers": {
    "fullcontact": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.fullcontact.com/v3/mcp",
        "--header",
        "Authorization: Bearer <your-fullcontact-api-key>"
      ]
    }
  }
}

⚠️
Two gotchas worth calling out

Use the absolute path to npx. Claude Desktop is a GUI app and does not inherit your shell PATH, so "command": "npx" will fail to launch. Run which npx in a terminal and paste that path — typical values are /opt/homebrew/bin/npx (Homebrew on Apple Silicon), /usr/local/bin/npx (Homebrew on Intel / Node.js installer), or ~/.nvm/versions/node/<version>/bin/npx (nvm).

Paste the literal API key into args. Claude Desktop does not interpolate ${VAR} substitutions inside args, and the env block on an MCP server entry does not affect how the args string is parsed. Put the actual key value in the Authorization: Bearer ... line. Treat the file like a credential — chmod 600 it on macOS/Linux if you're on a shared machine.

3. Fully quit and reopen Claude Desktop. Press ⌘Q (macOS) or File → Exit (Windows) — closing the window only is not enough; the app keeps running in the background and won't re-read the config. Open a new conversation. You should see a tools / hammer icon indicating that enrich_person is available. Try:

Enrich the person at [email protected] using FullContact.

4. If the tool doesn't appear, check the MCP server log:

tail -50 ~/Library/Logs/Claude/mcp-server-fullcontact.log    # macOS

Get-Content "$env:APPDATA\Claude\Logs\mcp-server-fullcontact.log" -Tail 50    # Windows

The most common failures are an unresolved npx path (use the absolute one), an outdated Node.js install (mcp-remote requires Node 18+), or a malformed JSON config (validate in any JSON linter before relaunching).

Claude Code

Claude Code (the Anthropic CLI) supports remote MCP servers through claude mcp add.

claude mcp add \
  --transport http \
  --header "Authorization: Bearer $FULLCONTACT_API_KEY" \
  fullcontact https://api.fullcontact.com/v3/mcp

To verify the connection:

claude mcp list

You should see fullcontact listed with a healthy status. Inside any Claude Code session, the enrich_person tool will be available as mcp__fullcontact__enrich_person.

📘
Tip
Use claude mcp add --scope user to make the server available across every project on the machine. Use --scope project (the default) to scope it to the current working directory only.

Gemini CLI

Gemini CLI loads MCP servers from ~/.gemini/settings.json (user scope) or .gemini/settings.json (project scope). You can configure the server through a shell command or by editing the settings file directly.

Option A — shell command (recommended). Mirrors the Claude Code pattern and writes the settings file for you:

gemini mcp add \
  --transport http \
  --header "Authorization: Bearer $FULLCONTACT_API_KEY" \
  fullcontact https://api.fullcontact.com/v3/mcp

Option B — edit settings.json directly. If the file does not yet exist, create it with an empty JSON object {} and then add the mcpServers block:

{
  "mcpServers": {
    "fullcontact": {
      "httpUrl": "https://api.fullcontact.com/v3/mcp",
      "headers": {
        "Authorization": "Bearer ${FULLCONTACT_API_KEY}"
      },
      "timeout": 30000
    }
  }
}

timeout is in milliseconds and is optional — Gemini CLI's default is 600000 ms (10 minutes). The value above (30 s) is a comfortable upper bound for enrich_person calls.

Verify the connection from the shell with gemini mcp list, or inside an interactive session with the /mcp slash command. Both should show fullcontact as CONNECTED. The first time the agent invokes enrich_person, Gemini CLI will display a tool-confirmation prompt — choose Always allow this server to suppress future prompts.

📘
Tip
Gemini CLI substitutes ${VAR} and $VAR (POSIX) and %VAR% (Windows) inside string values in settings.json; undefined variables resolve to an empty string, which will produce a 401 unauthorized from the server. Export FULLCONTACT_API_KEY in the shell that launches Gemini, or paste your literal key in place of ${FULLCONTACT_API_KEY} (not recommended on shared machines). If the server fails to connect, run gemini --debug to see the MCP handshake error.

Cursor

Cursor reads MCP configuration from ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

{
  "mcpServers": {
    "fullcontact": {
      "url": "https://api.fullcontact.com/v3/mcp",
      "headers": {
        "Authorization": "Bearer ${FULLCONTACT_API_KEY}"
      }
    }
  }
}

After saving, open the Cursor command palette and run MCP: Reload Servers. The enrich_person tool will appear in Cursor's tool list and is callable from Composer or the chat sidebar.

VS Code

The official MCP extension (or any MCP-compatible AI extension such as GitHub Copilot Chat in agent mode) reads server definitions from .vscode/mcp.json in your workspace, or from your user settings.json.

Workspace .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "fullcontact_api_key",
      "type": "promptString",
      "description": "FullContact API key",
      "password": true
    }
  ],
  "servers": {
    "fullcontact": {
      "type": "http",
      "url": "https://api.fullcontact.com/v3/mcp",
      "headers": {
        "Authorization": "Bearer ${input:fullcontact_api_key}"
      }
    }
  }
}

The first time you invoke a FullContact tool, VS Code will prompt for the API key and store it securely in the OS keychain.

ChatGPT (Custom Connector)

ChatGPT supports MCP servers as Custom Connectors for users on Plus, Pro, Business, Enterprise, or Edu plans with developer features enabled.

1. Open ChatGPT. Go to Settings → Connectors → Add custom connector.

2. Fill in the connector form:

Field	Value
Name	`FullContact`
Description (optional)	Resolve and enrich a person from email, phone, social, or name using FullContact.
MCP Server URL	`https://api.fullcontact.com/v3/mcp`
Authentication	API Key(sometimes labeled cusom, service authentication or Bearer token - not Oauth)
Token	Your FullContact API key

3. Save and enable the connector. Start a new chat with the connector turned on. The enrich_person tool will be discoverable by the model and callable in chat or in Deep Research workflows.

🔒
Note on Authentication
If the auth dropdown only offers OAuth and None — your account doesn't have custom-header auth enabled. This will not work for your account consider using another platform.

Verify the connection

Regardless of client, the easiest way to confirm the server is wired up is to ask:

Use the FullContact tool to enrich [email protected] and tell me their job title.

A working setup will return a structured profile within a few seconds. If you see an authentication error, double-check that your API key is set and that it has person.enrich access — see Authentication for troubleshooting.

Next steps

Authentication — How API key authentication and rate limiting work in detail.
Tool Reference: enrich_person — Full input/output schema with examples.
Errors and FAQ — Error codes and common questions.

Updated May 2026