---
updatedAt: 2026-04-30T18:09:59.000Z
agentTools:
  projectIndex: https://docs.fullcontact.com/llms.txt
---

# 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](https://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
```

***

<br />

## 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](https://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`).

<Callout icon="🔒" theme="default">
  ### **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`.
</Callout>

**2. Add the FullContact MCP Server entry.**

```json
{
  "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 <jane.doe@example.com> using FullContact.*

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

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

```powershell
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`.

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

To verify the connection:

```bash
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:

```bash
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:

```json
{
  "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).

```json
{
  "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`:**

```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.

<Callout icon="🔒" theme="default">
  ### **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.
</Callout>

***

## 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 `bart@fullcontact.com` 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](./03-mcp-authentication.md) for troubleshooting.

## Next steps

* [Authentication](./03-mcp-authentication.md) — How API key authentication and rate limiting work in detail.
* [Tool Reference: `enrich_person`](./04-mcp-tool-enrich-person.md) — Full input/output schema with examples.
* [Errors and FAQ](./05-mcp-errors-and-faq.md) — Error codes and common questions.

***

*Updated May 2026*