Helix docs

MCP — assistants & agents

Helix is a remote MCP server (Streamable HTTP) with self-issued OAuth 2.1. Point any MCP client at:

https://vault.helix.ai/mcp

Connection walks standard discovery → dynamic client registration → authorization with PKCE. The user signs in to their Helix and chooses scopes; tools are registered per-session from exactly what was granted. No likeness scope, no image tools — the tool list itself is scope-shaped.

Tools

get_context

Returns the user's vault as markdown, restricted to granted categories. Optional category argument narrows to one section. Every entry ends with a stable id tag like [#a1b2c3d]— keep these; they're how you supersede. Structured output includes granted_categories, pending_reviews and vault_kind.

vault_kind is "personal" or "household", because a grant names a vault rather than a person. It discloses the kind and never the membership. A vault that holds facts about someone who has not yet accepted that returns an error saying so rather than an empty vault: tell the user, and do not substitute your own memory of them. See Households & delegation.

propose_learning

Propose a durable fact about the user (third person, short). It is not saved— it enters the user's review queue. If your fact updates an existing entry, pass that entry's id as replaces: on approval Helix removes the old entry and adds yours in one action. Stale ids (the entry changed since you read it) degrade safely to a plain add.

propose_learning({
  category: "projects",
  fact: "Shipped the v2 redesign in July",
  replaces: "a1b2c3d",    // optional — id from get_context
  expires: "2026-12-31",  // optional — when it stops being true
  scope: "me"             // optional — "me" | "household"
})

Set expires whenever the thing is bounded: a trip, a rental, a sprint, a role someone is filling temporarily. You know that at the moment you write it and nothing reading the vault in six months can work it out from the text. On that date the user is asked whether to keep it. Nothing is ever removed silently.

scope only matters in a household. "me" (the default) means the person who connected you; "household" means the household as a whole. You cannot name another member: a fact about someone else is theirs to state.

list_subjects LIKENESS

Names and species of the user's likeness subjects — people and pets. Call before generate_image to resolve names. Reads are audited.

generate_image LIKENESS

Generate an image featuring vault subjects by name. Generation runs on the Helix server: reference photos go from the vault to the declared image provider, and you receive a one-hour linkto the finished image — the user's photos never enter the conversation, and your context never holds the artwork's bytes.

generate_image({
  subject_names: ["James", "Fergus"],
  prompt: "A vintage four-panel photobooth strip, warm sepia, playful poses"
})
// → { subjects, model, image_url }   (link valid 1 hour)

Behavior worth knowing

  • get_context appends a note when the user has proposals waiting — surface it; the review queue is how trust is maintained.
  • Tokens are revocable from the user's connections page and die immediately (HTTP 401 mid-session). Reconnect via OAuth; don't retry blindly.
  • Tool lists are granted-scope-dependent; if the user re-consents with different scopes, reconnect to refresh your tool cache.