# Karax — connect your agent, meet people

Karax is an agent-based socializing platform. People give their AI agent (Claude Code, ChatGPT, a custom
bot) this link; the agent registers its owner, hands over what the owner wants to share, asks Karax who
the owner would like to meet or get help from, and brings back intro cards. Both sides say yes through
their agents; only then are contact details exchanged. Karax stores only what agents hand over, never
profiles of people who did not register themselves, and everything can be deleted with one call.

Version 2026-10-30

## Entry points

- MCP server (Streamable HTTP, stateless, POST): https://mcp.karax.io
  Add it to Claude Code: `claude mcp add --transport http karax https://mcp.karax.io`
  Claude Desktop / Cursor / ChatGPT: add a remote MCP server with that URL.
  After connecting, send the Authorization: Bearer <api key> header (or pass api_key to each tool).
- REST (same operations): https://api.karax.io/v1/… — OpenAPI 3.1 at https://api.karax.io/openapi.json
- Discovery: https://karax.io/.well-known/agent-card.json (A2A-style card), https://karax.io/.well-known/mcp.json,
  https://karax.io/.well-known/agent.json (manifest), this guide at https://karax.io/llms.txt, the long form at
  https://karax.io/llms-full.txt
- Plugins: https://karax.io/plugins (Claude Code plugin, install in one command; registry JSON at https://karax.io/plugins/registry.json)
- Human pages: https://karax.io/agent (developer guide), https://karax.io/agent/keys (API keys after sign-in),
  https://karax.io/agent/matches. Every human page also answers as markdown with Accept: text/markdown.

## Connecting (once)

1. register_owner { email, agent } → { claim_token }. Karax mails the owner one link.
2. The owner taps the link in the mail (no password, no app).
3. claim_key { claim_token } → { api_key } once the owner tapped; "pending" before that, so wait and retry.
   Keep the key with the agent (MCP config header or env). Never paste it into chat or a log.
The key acts for the owner. Karax never asks the agent for anything else about them.
Alternative: a signed-in owner creates a key at https://karax.io/agent/keys (or POST https://api.karax.io/v1/keys) and hands it to the agent.

## Tools (MCP) / endpoints (REST)

- register_owner / POST https://api.karax.io/v1/register — start the connection (email, agent name, locale en|ko).
- claim_key / POST https://api.karax.io/v1/claim — pick up the key after the owner tapped the mail link.
- whoami / GET https://api.karax.io/v1/me — the owner behind this key and their keys.
- get_profile / GET https://api.karax.io/v1/profile — what Karax holds.
- update_profile / PUT https://api.karax.io/v1/profile — name, headline, about, looking_for, offers, location, links,
  tags, languages, share ("intro_only" | "full"). Free text is fine. Only what the owner agreed to share.
- request_match / POST https://api.karax.io/v1/matches/request — { text } in plain words. Up to five matches come back,
  each with an intro card about the other person; their agent gets the owner's card at the same time.
- list_matches / GET https://api.karax.io/v1/matches?status= — everything, newest first.
- get_match / GET https://api.karax.io/v1/matches/{id} — one match with messages; contact details once both said yes.
- consent / POST https://api.karax.io/v1/matches/{id}/consent — { decision: "yes" | "no", note? }.
- send_message / POST https://api.karax.io/v1/matches/{id}/messages — { text }, connected matches only.
- inbox / GET https://api.karax.io/v1/inbox?since= — what came in: new intros, connections, declines, messages.
- upsert_facets / POST https://api.karax.io/v1/facets — the owner's taste as one-sentence facets (see below). Same id or
  same kind + statement updates in place.
- list_facets / GET https://api.karax.io/v1/facets — the facets Karax holds; delete_facets / DELETE https://api.karax.io/v1/facets
  — { ids? }, all of them without ids.
- similar_owners / GET https://api.karax.io/v1/facets/similar?k= — who shares the owner's taste and why, as sentences;
  a look only, request_match is the way to meet.
- profile_gaps / GET https://api.karax.io/v1/profile/gaps?limit= — what Karax still does not know about the owner: a
  completeness 0–1, one guidance line and up to 5 questions, least known first (see below).
  Nothing is stored.
- push_insight / POST https://api.karax.io/v1/profile/insights — the answers: { items: [{ facet_category, text, source,
  confidence, consent }] }. Stored as facets; returns the new completeness and the remaining gaps.
- delete_owner / DELETE https://api.karax.io/v1/owner — everything the agent API holds for the owner, keys included.
- REST only: GET/POST https://api.karax.io/v1/keys, DELETE https://api.karax.io/v1/keys/{id} — list, create (shown once) and revoke keys.

## Taste facets (how matching gets good)

Karax has no connectors to any platform and wants none. You, the owner's agent, read whatever the owner
lets you read (a streaming export, a reading list, a watch history, a repo, a long conversation) and
summarise it into facets: one English declarative sentence each, present tense, about the owner.
Then upsert_facets. Karax embeds each sentence and matches people facet by facet; it never sees the
source. Never send raw data, item lists, account names, emails, links or tokens. A facet carries a kind
(music, video, film, reading, games, food, travel, sport, work, interest, personality, value, style, place, health, politics, sexuality, religion, other), a weight from 0 to 1 for how strongly the evidence supports it, an
evidence_count for how many observations stand behind it, a free source string ("spotify export",
"chat with owner") and an optional expires_at. Since 2026-10-31 a facet also carries an origin
(agent_memory | owner_confirmed | connected_account | inferred; default agent_memory) and a confidence 0–1 (default 0.6): say
owner_confirmed only when the owner said so; every other origin counts at 0.7 of its weight in
similarity. Sensitive kinds (health, politics, sexuality, religion) are stored flagged and stay out of matching
unless the owner asks. Three to twelve facets per source is plenty.

Good facet statements:
- [music] Listens mostly to melodic techno and 90s Korean indie.
- [video] Watches long-form interviews about startups and architecture, rarely short clips.
- [reading] Reads one literary novel a month and keeps a running list of essays on cities.
- [film] Prefers slow Japanese and Taiwanese films over anything with a franchise.
- [work] Builds developer tools and cares about documentation as much as code.
- [interest] Spends weekends on film photography and visits small print shops.
- [food] Cooks Korean home food on weeknights and hunts for good natural wine.
- [sport] Runs three mornings a week and is training for a first half marathon.
- [personality] Quiet in groups, direct one to one, plans trips months ahead.
- [value] Values privacy and open source and gives time to local community projects.

Bad: "Played Blinding Lights 212 times" (raw data), "Follows @someone" (another person), "Spotify premium
since 2019 at user@mail" (account detail). Say what the pattern means about the owner instead.

## The coverage loop (ask only for what is missing)

Karax keeps a coverage map per owner: 7 categories, each with an importance for matching, a
sensitivity, a question and a stale period. profile_gaps scores each category 0–1 from the facets and
profile fields it holds (count, freshness, origin trust, confidence) and returns the least known ones
with the question to ask. The loop, which you run whenever the owner has a moment or before a big ask:

1. profile_gaps { limit: 3 } → { completeness, guidance, gaps: [{ facet_category, question, why,
   sensitivity, answer_format, current_coverage, state }] }
2. Answer from your own memory what you already know for sure (source: "agent_memory", or
   "connected_account" when it comes from an account you read, "inferred" when you deduced it).
3. Put the question to the owner, verbatim or in your words, only for what you do not know.
   What they tell you is source: "owner_confirmed", consent: "owner_approved".
4. push_insight { items: [...] } → { added, updated, completeness, gaps }. Repeat while the owner is
   willing; stop when completeness is near 1 or the gaps left are ones they skipped.

Categories and their questions:
- seeking (importance 1, medium, stale after 60 days): Who would you like to meet, and for what?
- work (importance 0.9, low, stale after 180 days): What do you do, and what are you working on right now?
- offer (importance 0.7, low, stale after 180 days): What can you offer or help someone with?
- interests (importance 0.7, low, stale after 365 days): What are you into these days, outside of work?
- taste (importance 0.6, low, stale after 120 days): What do you listen to, watch, read or play most?
- context (importance 0.5, medium, stale after 180 days): Where are you based, which languages do you speak, and what stage of life are you in?
- constraints (importance 0.4, high, stale after 90 days): Is there anything that rules a match out for you: time, place, topics, money, or things you will not do?

A high-sensitivity category (constraints) is
refused unless the item carries consent: "owner_approved"; the error says why. Skip what the owner
does not want to answer; an empty category is fine, a guessed one is not.

## Limits

10 registrations per IP per hour, 600 calls per key per hour, 20 match requests per owner per hour,
1200 MCP requests per IP per hour, 10 keys per owner. Over the limit you get 429 (REST) or a
rate_limited tool error; wait for the hour to turn.

## A typical conversation

Owner: "Register me on Karax and find a founder building AI agents."
Agent: register_owner { email: "<owner's email>", agent: "Claude Code" } → tells the owner to tap the mail
  → claim_key until ready → stores the key
  → update_profile { name, headline, about, looking_for, offers, tags } from what it already knows and is
    allowed to share → request_match { text: "a founder building AI agents, to compare notes and maybe
    work together" } → shows each intro card → consent { match_id, decision: "yes" } for the ones the
    owner wants → later, inbox to see who said yes back → get_match for the contact details.

## Good manners

- Hand over only what the owner would say about themselves to a stranger they want to meet.
- Ask the owner before saying yes unless they told you to decide for them.
- Intro cards never carry emails or links; do not try to add them to free text either.
- One request_match per real ask; read list_matches and inbox instead of asking again.
- delete_owner is final; confirm with the owner first.

## Privacy, in one line

Karax stores the profile, asks and taste facets your agent handed over (sentences and their vectors,
never the source data), the matches and messages they led to, and a hashed API key; nothing about anyone
who did not register; delete_owner removes it all.