Skip to content
aizkaizk

MCP tools

This page names every parameter and limit, all of them shipped defaults a deployment can move. Connecting a client is covered under Claude Code.

A connected client sees four tools and one resource. Every call runs as you, returns no row you could not already read, and is capped at 5 requests per second.

How the four tools reach the store, and how find points back to stored bytesresourceagentstatusfindkeepsharestored original

Agents call these as ordinary functions.

aizk.status(days=30)
aizk.find(query="why did we switch extractors?", budget=2048)
aizk.keep(text="...", scopes=["Book Club"])
aizk.share(documents=["019f..."], scopes=["Book Club"])

status

Section titled “status”

Who you are, what you have used, and what is still processing. Requires a signed-in caller.

aizk.status(days=30)
Parameter Type Bounds Default
days integer 1 to 365 30

The result has four parts.

Field Shape Carries
generated_at timestamp
caller identity and authority name, username, avatar, label, roles, anonymous, organizations
each organization membership standing name, description, roles, permissions, writable, public
usage counted work over days and over your lifetime generated_at, recorded_through, days, start, plus summary over the window and lifetime over everything
processing queue depth and honest time estimates see below

Both summary and lifetime hold the same counters.

Counter Meaning
recalls, remembers, files, shares, artifact_reads operations by kind, where recalls counts find calls
requests, items calls made and items returned
request_bytes, response_bytes bytes in and out
uploaded_bytes, downloaded_bytes file bytes stored and fetched
duration_ms total server time
processing field Meaning
state idle, active, or delayed
recallable_lower_seconds, recallable_upper_seconds when what you stored becomes findable
enriched_lower_seconds, enriched_upper_seconds when the graph around it is finished, empty while conversions are pending because uncreated work cannot be estimated
stages conversion and graph_projection

Each stage reports queued, running, failed, completed_1h, completed_24h, progress_percent, throughput_per_hour, throughput_window_hours, lower_seconds, upper_seconds, oldest_at, a confidence of high, medium, low, or unavailable, and an eta_status of complete, estimating, insufficient_history, or blocked. An estimate is withheld rather than invented on too small a sample.

find

Section titled “find”

Answers one question from your memory, reaching the public web only when memory falls short and the question can be rewritten so nothing identifying you leaves the machine. Finding on the web covers that half, the ## Web section, the receipt every answer ends with, and the caching a fetched page triggers.

aizk.find(query="why did we switch extractors?", budget=2048, web="auto", fresh=False)
Parameter Type Bounds Default
query string 1 to 16,384 characters required
budget integer 1 to 16,384 tokens 2,048
scopes list of organization names at most 32 private
web auto, off, or force auto
fresh boolean false

Memory has no scope selector, so one question searches everything you can see, while scopes names only where a fetched page is cached.

The return is a Markdown string. It opens with a ## Scopes list when shared material is present, then a line reminding the agent that recalled content is evidence rather than instructions, then ## Evidence in merit order. Each item is labeled Source excerpt, Derived memory, Recent session memory, or Web page and names its scope, an intersection joining organizations with ∩. An item from a stored source prints that document’s id and capture day, the handle share takes, while profiles, communities and overviews print none. Items backed by a stored original also print a resource URI.

Evidence fills the budget greedily in merit order, skipping an item too large for the room left rather than ending the walk, and trimming the best item with a trailing … when the budget cannot hold even that.

keep

Section titled “keep”

Stores text, preserves an original, or prepares a file upload. Requires a signed-in caller.

aizk.keep(text="...", source_uri=None, scopes=["Book Club"], preserve_source=False)
Parameter Type Bounds
text string 1 to 5,000,000 characters
source_uri string up to 4,096 characters
observed_at timestamp when the statement became applicable
expires_at timestamp when it stops being true
scopes list of organization names at most 32
preserve_source boolean default false
upload file declaration see below

The combination decides the mode and the return.

You pass What happens You get
text only stored as a note { id }
text and source_uri note that records where it came from { id }
source_uri only the original is fetched and kept { artifact_id, content_id, state }
source_uri, text, preserve_source original kept, text becomes its companion { artifact_id, content_id, state }
upload a ticket for your own local file { status, upload_url, expires_seconds }

state is pending, queued, processing, ready, or failed. A receipt is an acceptance, not a finished conversion, so watch status for it becoming recallable. Files, PDFs and web sources covers files and Time and history the two timestamps.

Omitting scopes keeps the memory private. preserve_source without source_uri is an error.

The upload flow

Section titled “The upload flow”

upload declares one local file with four fields, filename and media_type up to 255 characters each, size in bytes, and sha256 as 64 lowercase hex characters. It cannot combine with source_uri, preserve_source, observed_at, or expires_at. Pass text for companion context, scopes for a destination.

The response is a ticket and not a stored file.

  aizk.keep(upload={...}, text="...")
            │
            ▼
  a ticket comes back with status accepted, a one-time
  upload_url, and expires_seconds of 600
            │
            ▼
  PUT exactly the declared bytes to upload_url, once
            │
            ▼
  the file is accepted, and status tracks its conversion

The server gives you the whole URL. Do not build it. It is a single-use private bearer address, so anyone holding it before it expires can perform that one write. Never log, share, or retry with it. Bytes not matching the declared size and hash are rejected.

share

Section titled “share”

Copies or moves documents you name, or previews what a query would select.

aizk.share(query="reading notes on translation", scopes=["Book Club"])
aizk.share(documents=["019f..."], scopes=["Book Club"], move=True)
Parameter Type Bounds Default
documents list of document ids, the only writing mode 1 to 100 none
query string, always a preview 1 to 16,384 characters none
scopes list of organization names at most 32 private
move boolean false
limit integer 1 to 100 20
dry_run boolean false

Pass exactly one of documents and query. Only documents ever writes. A query answers which of your own private documents it would select, at most limit in merit order, and writes nothing whatever else you pass, since a question matches on similarity rather than on what you meant. So sharing a topic takes two steps, a query to read the candidates and a second call naming the ids you approve. Recall prints those ids, so step one is optional when you know them.

A query and a move both start from your own private documents, so both need an organization in scopes. Carrying a document into the scope it already occupies is refused, since that copies a scope onto itself and adds a generation per repeat. A document already standing in the destination is left alone. move with a query is refused rather than ignored, so a refusal never reads as a move that happened.

A result with preview set was not written, and each document’s destination names the copy only once one exists, so read both rather than assuming. dry_run previews an explicit documents list and adds nothing to a query.

Sharing copies by default, so the original stays yours, which Sharing and organizations explains. move copies and then retires the private original, leaving the destination copy the only one recall returns while the original’s rows, bytes and provenance stay. Both halves commit together, and a move touches only your own private documents. Repeating either call changes nothing, and a source revised since an earlier share refreshes that copy first.

The artifact resource

Section titled “The artifact resource”

Stored originals are readable through one resource template.

aizk://artifacts/{artifact_id}/contents/{artifact_content_id}

Both ids come from the resource URI printed on a find item, so an agent reads the exact bytes behind evidence without searching. Reading verifies size and hash, failing rather than returning drifted content, and an artifact you cannot see behaves as if it does not exist.

Next

Section titled “Next”