Errors and FAQ

Error reference

The MCP Server normalizes all upstream and validation failures into a consistent error shape so AI agents can reason about them without parsing FullContact REST conventions.

Error envelope

{
  "error": {
    "code": "<machine_readable_code>",
    "message": "<human-readable explanation>",
    "request_id": "<id for support tickets>",
    "retry_after_seconds": 30
  }
}

code — Stable, machine-readable identifier suitable for branching in agent prompts.
message — Short human description. Safe to surface to end users.
request_id — Always included. Provide this to FullContact support when filing issues.
retry_after_seconds — Present only on retryable errors.

Error codes

Code	HTTP analog	Retryable	Meaning
`unauthorized`	401	No	Missing or invalid `Authorization` header.
`forbidden`	403	No	API key is valid but lacks `person.enrich` entitlement.
`invalid_input`	400	No	Request did not satisfy the input schema (e.g., `location` without `name`).
`not_found`	404	No	No person matched the supplied identifiers.
`rate_limit_exceeded`	429	Yes	Account rate limit hit. Honor `retry_after_seconds`.
`upstream_unavailable`	502 / 503	Yes	Transient failure calling `person.enrich`.
`upstream_timeout`	504	Yes	`person.enrich` did not respond within the configured timeout.
`internal_error`	500	No	Unexpected MCP Server failure. Open a support ticket with `request_id`.

📘
Note
not_found is not an error in the agentic sense — it simply means the identity graph does not have a match. Agents should treat it as a normal "miss" and continue.

FAQ

Do I need a separate API key for MCP?

No. The MCP Server reuses the same FullContact API key you use for direct REST calls. See Authentication.

How are calls billed?

A successful enrich_person invocation counts as one person.enrich call against your account. not_found and invalid_input responses also count as one call, consistent with the underlying API. Errors that originate inside the MCP Server itself (unauthorized, internal_error, upstream_timeout) do not count.

Which AI clients are supported?

Any MCP-compliant client. We publish first-class Quickstarts for Claude Desktop, Claude Code, Gemini CLI, Cursor, VS Code, and ChatGPT. New clients adopting the protocol will work without changes to the server.

Does the MCP Server store my customer data?

No. Inputs and responses pass through in memory only. Operational logs include request IDs and latencies but never the identifiers themselves. See Compliance and PII handling.

Can I use hashed emails?

Yes. MD5, SHA-1, and SHA-256 hashes of emails are passed through to person.enrich unchanged. When only hashed identifiers are supplied, the response will omit clear-text PII fields per FullContact's privacy controls.

What about company enrichment, Resolve, or Acumen?

The initial release wraps person.enrich only. Additional FullContact APIs will be exposed as MCP tools in future releases.

How do I rotate my API key?

Generate a new key in the developer dashboard, update each MCP client (env var, connector token, or VS Code prompt), and revoke the old key. The MCP Server holds no cache of its own — the next request from each client uses the new value automatically.

What is the latency overhead of the MCP Server?

The server adds at most 50 ms of P95 overhead on top of the underlying person.enrich call. End-to-end latency is dominated by the upstream API.

How do I report a bug?

Capture the request_id from the error envelope and email [email protected] or file a ticket through your account team. Include the client you were using (Claude Desktop, Claude Code, Gemini CLI, Cursor, VS Code, or ChatGPT) and the approximate timestamp of the failed call.

Updated May 2026