← Documentation / MCP

MCP quickstart

uniqueness-mcp is a local MCP server (npm package, no hosted endpoint) that gives any MCP-compatible agent a conservative wrapper around the API: enrich one person, resume a human-approved payment-required request, inspect billing, preflight a batch, and send feedback. It never purchases a pack, saves a payment method, enables auto-recharge, or subscribes by inference.

Available tools: begin_programmatic_signup, complete_programmatic_signup, get_connection_brief, resume_connection_brief, get_billing_status, preflight_connection_briefs, and submit_feedback.

1. Get a key first

MCP needs a revocable key on the environment. Call begin_programmatic_signup with a human-controlled email, have that human approve the named device in email, then call complete_programmatic_signup with the returned continuation ID. The polling secret stays inside the MCP process. A key is issued only after the service reports approval and is never repeated in MCP output. A successful completion configures the currently running MCP process only. For a durable named key or a future config, a human signs in to Account; the agent must not expose or relay a key.

2. Add to your MCP config

{
  "mcpServers": {
    "uniqueness": {
      "command": "npx",
      "args": ["-y", "uniqueness-mcp"],
      "env": { "UNIQUENESS_API_KEY": "uq_live_..." }
    }
  }
}

Works anywhere MCP config JSON is accepted: Claude Desktop/Code, Cursor, and any other MCP-compatible client.

3. Call the tool

Tool name: get_connection_brief. Under the hood it submits to the async POST /api/enrich endpoint and polls GET /api/jobs/:id for you until the brief is ready, so a single tool call returns the finished brief. Cache hits come back instantly; a fresh, uncached profile usually resolves in 45–90s (rarely up to ~3 min). If a brief takes longer than the polling window, the tool hands back the job_id with a note — just call it again with the same inputs to keep polling (the brief is often cached by then). See /documentation for the raw async flow. Input shape:

{
  "linkedin_url": "https://www.linkedin.com/in/<their-handle>"
}
// or: { "name": "...", "company": "..." }
// optional: "detail": "compact" | "full" (set it explicitly)

Want to see the response shape without a key or a credit? Use the fictional static Jordan Ellis fixture directly at GET /api/examples/kitchen-sink (persona "Jordan Ellis", mode:"synthetic_fixture"). It never runs live enrichment. The full machine-readable contract lives at /openapi.json.

4. Expected responses

Resolved (ok) — full by default in production; pass detail:"compact" for the smaller shape. This explicit compact example omits the breakdown arrays, sub-scores, and top-level evidence[]:

{
  "status": "ok",
  "identity": { "full_name": "...", "title": "...", "company": "...", "identity_confidence": 0.92 },
  "safe_to_reference": [
    { "claim": "...", "evidence_quote": "grounded text from the source",
      "source_url": "...", "connection_type": "personal_signal",
      "category": "hobby_public", "band": "safe", "mentionability": 0.9 }
  ],
  "personality": { "archetype": "...", "disc_label": "...", "how_to_communicate": ["..."], "predicted": true },
  "capabilities": { "outreach_angles": "removed", "gift_hook": "disabled", "detail": "compact", "full_available": true },
  "usage": { "cache_status": "hit|miss", "credits_charged": 1, "credits_remaining": 9 }
}

The removed fields outreach_angles, gift_hook, and per-claim safe_to_use_in_outreach are declared in capabilities and never returned. An invalid detail value returns 400 invalid_detail.

Refused (needs_review — not an error, never charged):

{
  "status": "needs_review",
  "identity": { "identity_confidence": 0.4, "status": "needs_review" },
  "usage": { "credits_charged": 0 }
}

5. Insufficient credit is a human action

A real enrichment uses one full-quality written credit. New accounts start with zero live credits; the paid evaluation entry point is the permanent 5-Pack (five credits, $5 USD subtotal plus tax). On an insufficient balance, get_connection_brief returns a structured human_action_required payload containing the canonical 402 payment_required contract and a target-free Checkout link. The agent must first show the pack terms and obtain explicit human consent. Only then may it surface recommended_offer.checkout_url for the offered pack, or billing_url if the human wants to choose another pack. It must not purchase, save a card, enable auto-recharge, or accept a claim that payment happened.

{
  "status": "human_action_required",
  "action": "checkout",
  "payment_required": {
    "error": "payment_required",
    "credits": { "required": 1, "available": 0, "shortfall": 1 },
    "recommended_offer": {
      "id": "five_pack", "credits": 5, "subtotal_amount": 500,
      "checkout_url": "https://…/target-free-offered-pack",
      "expires_at": "…"
    },
    "billing_url": "https://…/target-free-pack-selector",
    "retry": { "mode": "resubmit", "idempotency_key": "...", "expires_at": "..." }
  },
  "resume_tool": "resume_connection_brief",
  "resume_requires": [
    "original target fields",
    "payment_required.retry.idempotency_key",
    "payment_required.credits.available"
  ]
}

After the human completes Checkout, call resume_connection_brief with the original target, payment_required.retry.idempotency_key, and payment_required.credits.available. The server checks its current spendable balance before submitting, and the API rejects a changed target under the same retry key. If the Checkout or retry expiry has passed, submit a new request; it receives a new key. The MCP server stores no unpaid target.

6. Billing and batch safety

get_billing_status is read-only and shows subscription, grandfathered, service-recovery, and purchased-credit provenance. Auto-recharge is optional, off by default, and requires separate explicit human consent; an action_required attempt never retries automatically. preflight_connection_briefs is also read-only. A real batch is all-or-nothing: it reserves the deterministic maximum before work starts and never triggers auto-recharge.

Verified working

Initializes over stdio and lists enrichment, explicit human-action, read-only billing/preflight, and feedback tools.
Real calls return real ok/needs_review responses — same engine as the direct API.
Don't use generated interests unless they come from safe_to_reference (source URL + evidence quote that passed normalized grounding) or clearly labeled aggregated_interests (directional, not a quote). negative_preferences remains in the full schema but is currently disabled and normally returns [].

Full endpoint reference: /documentation. One-shot agent setup instead: /agents.