MCP quickstart

The hosted MCP at https://uniquenessengine.com/mcp is the primary integration. It uses Streamable HTTP and the same uq_* bearer keys as the API. Compatible fixes arrive without a package reinstall; refresh the client catalog only when a tool schema changes. uniqueness update does not update this server. There is no rotate-key tool.

Lifecycle tools include get_personal_context, get_connection_brief_job, batch_connection_briefs, get_batch_status, get_batch_results, export_batch, cancel_job, retry_job, and retry_failed_batch.

1. Get a key first

A human creates or rotates a revocable key in Account, then stores it in the MCP client's secret configuration. The hosted endpoint does not expose signup credentials through stateless tool calls.

2. Add to your MCP config

{
  "mcpServers": {
    "uniqueness": {
      "url": "https://uniquenessengine.com/mcp",
      "headers": { "Authorization": "Bearer uq_live_..." }
    }
  }
}

Clients that cannot use remote Streamable HTTP or cannot set a bearer header can run npx -y uniqueness-mcp@latest as a local stdio fallback with UNIQUENESS_API_KEY. Only that fallback exposes begin_programmatic_signup and complete_programmatic_signup; they configure the currently running process only after human email approval.

3. Call the tool

Tool name: get_personal_context (alias get_connection_brief). Under the hood it submits to the async POST /api/enrich endpoint. Cache hits return inline. Fresh work returns a job_id; call get_connection_brief_job with that ID until it is terminal. Do not resubmit the person to poll. See /documentation for the raw async flow. Input shape:

{
  "linkedin_url": "https://www.linkedin.com/in/<their-handle>",
  "detail": "compact"
}
// or: { "name": "...", "company": "...", "detail": "compact" }
// MCP defaults to detail:"compact" when omitted. Pass "full" for provenance sub-scores.
// refresh:true only when the user asks to rerun / refresh / re-enrich / check new UE changes.
// Ordinary repeat reads omit refresh. Do not resubmit while polling a job_id.
// A repeat lookup with cache_status=hit is not a fresh enrichment.

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?detail=compact (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) : MCP defaults to detail:"compact" (recommended for agents). Pass detail:"full" for debugging, eval, or a trust UI that needs provenance sub-scores. Compact still includes every field you would filter on:

{
  "status": "ok",
  "identity": { "full_name": "...", "title": "...", "company": "...", "identity_confidence": 0.92 },
  "facts": [
    { "claim": "...", "evidence_quote": "grounded text from the source",
      "source_url": "...", "connection_type": "personal_signal",
      "category": "hobby_public", "confidence": 0.65, "confidence_label": "high",
      "mentionability": 0.9, "sensitivity_score": 0.05,
      "verdict": "entailed", "special_category": false }
  ],
  "discovered_handles": { "x": "https://...", "github": "https://..." },
  "personality": { "archetype": "...", "disc_label": "...", "how_to_communicate": ["..."], "predicted": true },
  "detail": "compact",
  "usage": { "cache_status": "hit|miss", "credits_charged": 1, "credits_remaining": 9 }
}

Compact (the MCP default) includes discovered_handles — a platform → profile URL map — alongside facts and personality. Provenance tiers (handle_sources) stay on detail=full only.

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 one-time Intro 10 (ten credits, $5 USD subtotal plus tax, first pack purchase only). On an insufficient balance, get_personal_context 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": "intro_10", "credits": 10, "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_personal_context",
  "resume_requires": [
    "original target fields",
    "payment_required.retry.idempotency_key",
    "payment_required.credits.available"
  ]
}

After the human completes Checkout, call resume_personal_context (alias 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_personal_contexts (alias 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 facts (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. CLI skill: /SKILL.md.