Welcome to FullContact Support

Search our Knowledge Base or Contact Support.

Authentication

On this page

• Authentication

Authentication

The FullContact MCP Server is authenticated with the same API key you use for direct calls to the FullContact REST API. There is no separate MCP credential, no OAuth flow, and no need to provision new accounts. If your API key can call person.enrich today, it can drive the MCP Server tomorrow.

Get an API key

If you do not yet have a key, see Generate an API Key. The key must:

• Belong to an active FullContact account.
• Have person.enrich included in its product entitlements.
• Be a production key for production traffic; sandbox keys are accepted for evaluation only.

📘 Note
A single API key can be used across multiple AI clients simultaneously (e.g., Claude Desktop on a developer's laptop and a hosted Cursor workspace). All calls count against the same rate limit and quota.

How the key is passed

The MCP Server expects the key in the standard Authorization HTTP header on every request from the client:

Authorization: Bearer <your-fullcontact-api-key>

Each client configures this differently. The patterns used in our Quickstarts are:

Client-specific configuration:

• Claude Desktop — Literal value pasted into the Authorization: Bearer ... string inside args in claude_desktop_config.json (Claude Desktop does not interpolate env vars into args). Forwarded by the local mcp-remote bridge as the Authorization header on every HTTP request.
• Claude Code — --header flag on claude mcp add. Sent on every MCP request.
• Gemini CLI — headers block in ~/.gemini/settings.json (env-var substitution supported). Sent on every MCP request.
• Cursor — headers block in mcp.json. Sent on every MCP request.
• VS Code — inputs prompt or workspace secret, referenced in headers. Sent on every MCP request.
• ChatGPT — Token field on the Custom Connector. Stored in ChatGPT's encrypted credential store.

In every case the key is sent server-to-server over TLS and is never logged in plaintext by the MCP Server.

Rate limiting and quotas

The MCP Server enforces the same rate limits and monthly quotas as the underlying API. A successful enrich_person invocation counts as oneperson.enrich call against your account.

When the limit is exceeded, the server returns a normalized error so the agent can back off gracefully:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "request_id": "01HW6Q8K9XYZ...",
    "retry_after_seconds": 30
  }
}

See the Errors reference for the full error taxonomy.

Key rotation

To rotate a key:

1. Generate a new key in the FullContact developer dashboard.
2. Update the credential in each MCP client (env var, connector token, or VS Code prompt).
3. Revoke the old key once all clients have been updated.

Because the key only ever lives client-side, there is no MCP-Server-side cache to invalidate. The next request from each client will use the new value automatically.

Compliance and PII handling

• No persistence. The MCP Server processes inputs in memory and does not write enrichment payloads to disk.
• PII-safe logging. Operational logs include request IDs, latency, and error codes only. Identifiers passed in (emails, phones, names) are not logged.
• Hashed inputs supported. You can pass MD5, SHA-1, or SHA-256 hashes of email addresses; the server forwards them unchanged. When hashed identifiers are used without a paired clear-text identifier, FullContact's API will not return clear-text PII fields in the response — see the Multi-Field Request guide for details.
• SOC 2. The hosted MCP Server runs inside FullContact's existing SOC 2 boundary.

Troubleshooting

Next steps

• Tool Reference: enrich_person — Full input/output schema.
• Errors and FAQ — Complete error taxonomy and common questions.