Connect over MCP

The Hunta memory engine is an MCP server (Streamable HTTP) at https://mcp.hunta.ai/mcp. Any MCP client connects with a bearer token; the tenant is bound to the token, never passed as a parameter.

Generic MCP client

Most clients accept an mcpServers block:

{
  "mcpServers": {
    "gather": {
      "url": "https://mcp.hunta.ai/mcp",
      "headers": { "Authorization": "Bearer <your-agent-key>" }
    }
  }
}

Codex (TOML)

[mcp_servers.gather]
url = "https://mcp.hunta.ai/mcp"

[mcp_servers.gather.http_headers]
Authorization = "Bearer <your-agent-key>"

What your agent gets

The server exposes memory as branded tools your agent calls by name:

gather writes a memory to canon (owner keys); capture proposes one into the review queue (agent keys)
recall and search read sealed facts back, with provenance and point-in-time (as_of)
facts and fact list and inspect the current canon; supersede_fact and invalidate_fact correct it
the Instinct reflex set (check_errata, propose_errata, capture_errata), plus curation actions (candidates, promote_candidate, reject_candidate, consolidate_candidate, reconcile) with the right scopes

These are the same three verbs as the REST API (Gather, Recall, Instinct); see the API reference. Scopes on the token decide what a given agent can do:

Scope	Allows
`memory:read`	recall and search, facts, Instinct gate query, metrics, attestation
`memory:capture`	propose candidates into the staging queue (`capture`, `propose_errata`)
`memory:write`	direct writes to canon (owner tooling), forget; also satisfies every `capture` and `curate` check
`memory:curate`	promote, reject and consolidate candidates, supersede and invalidate facts, reconcile

Give harness agents capture plus read. Keep write and curate for owners and trusted tooling. The backend enforces scopes server-side, so a mis-scoped client cannot exceed them: a tool called without its scope fails with insufficient_scope. The legacy scope memory means full access. memory:admin and memory:provision also exist (tenant settings and portal provisioning) but are not customer-mintable.

Tool reference

Every tool operates only on the caller's own tenant. Parameters marked optional have the default shown.

Gather (write)

Tool	Scope	Parameters
`gather`	`memory:write`	`text`; `agent` = `"default"`; `valid_from` (ISO-8601 event-time, not future); `supersedes` (id of the current fact this text replaces, new in 0.58.0: that fact is closed bi-temporally and `text` is put in force as its successor, verbatim, without running the extractor). Returns `{id, tenant}`.
`capture`	`memory:capture`	`text`; `agent` = `"default"`; `source` = `"api"`. Stages a candidate; returns `{candidate_id, tenant, status: "pending"}`. Candidates never appear in recall or search until promoted.
`forget`	`memory:write`	`memory_id`. GDPR cascade: deletes the raw memory, every fact derived from it and any orphaned entity. Preview with `facts(source_memory_id=...)` first.

Recall (read)

Tool	Scope	Parameters
`recall`	`memory:read`	`query`; `limit` = 10. Most relevant current facts (with `source_memory_id` and `valid_from`), else raw memories.
`search`	`memory:read`	`query` = `""` (empty = filter-only listing); `limit` = 10; `agent`; `as_of` (ISO-8601, facts in force at that instant); `entity` (facts about a named entity).
`memory_metrics`	`memory:read`	none. Counts, facts versus raw, unprocessed backlog, decrypt-failure counter, extractor egress, last attestation.

Facts

Tool	Scope	Parameters
`facts`	`memory:read`	`source_memory_id`; `include_superseded` = false; `limit` = 50. Facts with slot, `valid_from` / `valid_to`, `superseded_by`, `retraction_reason`. (The REST `GET /v1/facts` also takes `superseded_by`.)
`fact`	`memory:read`	`fact_id`. One fact plus `created_at`, `corroboration_count` and entity `names`; `null` if absent.
`supersede_fact`	`memory:curate`	`fact_id`; `statement`; `agent`; `valid_from`. Closes the target bi-temporally and puts `statement` in force as its successor; the extractor is not run.
`invalidate_fact`	`memory:curate`	`fact_id`; `reason`. Retracts a fact with no successor; `reason` is stored encrypted.
`forget_fact`	`memory:write`	`fact_id`. Erases one fact; siblings and the source memory survive. Deliberately not available to curate-only keys.

Candidates (the review queue)

Tool	Scope	Parameters
`candidates`	`memory:curate`	`status` = `"pending"` (`pending`, `promoted`, `rejected`, `expired`); `limit` = 20; `kind` (`fact` or `breadcrumb`).
`promote_candidate`	`memory:curate`	`candidate_id`; `text` (a distilled statement to store instead of the raw capture); `agent`. Who promoted and the lane are stamped from your token.
`reject_candidate`	`memory:curate`	`candidate_id`. Kept as `rejected` for audit, stamped with who rejected it.
`consolidate_candidate`	`memory:curate`	`candidate_id`; `action`; `symptom`; `guidance`; `retire_slots`; `severity`. Admits a merge proposal as one curator-composed Instinct entry and retires the entries it replaces.
`reconcile`	`memory:curate`	`limit` = 50 (max 200); `retriage` = false. One two-lane triage pass over pending candidates; returns the run report.

Instinct

Tool	Scope	Parameters
`check_errata`	`memory:read`	`action`. Deterministic, action-keyed lookup of the current governed entries; the gate query to run before a risky action.
`propose_errata`	`memory:capture`	`action`; `symptom`; `retrieval_keys` (dict of short strings, max 16 keys). Stages an Instinct candidate; a curator adds the guidance at promotion.
`capture_errata`	`memory:curate`	`action`; `symptom`; `guidance`; `valid_from`; `severity`. Curated write of a governed entry. Re-capturing the same symptom with new guidance supersedes the prior entry.

Tenant settings and identity

Tool	Scope	Parameters
`set_reconcile_mode`	`memory:admin`	`mode` (`off`, `shadow`, `on`, or null to clear). Per-tenant reconciler posture override.
`set_auto_sources`	`memory:admin`	`sources` (list of capture `source` tokens, or null to clear). Which sources the auto lane may admit.
`retry_extraction`	`memory:admin`	`limit` = 50 (max 500). Re-runs fact extraction on memories a prior extractor failure left unprocessed.
`verify_isolation`	`memory:read`	`nonce`. Your tenant's Ed25519-signed isolation attestation; the nonce is echoed into the signed manifest.
`whoami`	any valid key	none. Returns `{tenant, subject, scopes}`.

memory:write also satisfies the memory:capture and memory:curate checks above. The memory:admin tools are tenant settings the console manages for you; that scope is not mintable from the Keys page.

REST instead of MCP

Everything is also plain REST on the same host. See the API reference.

On this page