@ainize/mcp
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AINIZE_TOKEN | No | An existing operator session token instead of the password | |
| GRAPH_API_KEY | No | The Graph gateway key — used by the MCP client example only, never by a tool | |
| AINIZE_NODE_URL | No | The node this server speaks for — configuration, not a tool argument | http://localhost:3422 |
| AINIZE_TEACH_KEY | No | 64-hex teaching key, or a path to the key-backup JSON | |
| AINIZE_MCP_CONFIG | No | A JSON file with the same keys in snake_case; env wins over it | |
| AINIZE_MCP_POLL_MS | No | How often a running lesson is re-read from the node | 3000 |
| AINIZE_MCP_STATE_DIR | No | Where the purchase journal and provenance records are persisted (mode 0600); memory only by default | |
| AINIZE_MCP_ALLOW_APPLY | No | Register apply_knowledge / remove_knowledge; off by default | off |
| AINIZE_MCP_DOWNLOAD_DIR | No | Where download_lesson writes files; defaults to <state dir>/lessons, else the temp dir | |
| AINIZE_MCP_ALLOW_PUBLISH | No | Register publish_knowledge (irreversible); off by default | off |
| AINIZE_OPERATOR_PASSWORD | No | Exchanged once at startup for an in-memory bearer | |
| AINIZE_MCP_MAX_TEACH_JOBS | No | Daily lessons this server may spend | 1 |
| AINIZE_MCP_SESSION_BUDGET | No | Total spend allowed for the life of this process; default 0 means buy is not registered | 0 |
| AINIZE_MCP_MAX_DOWNLOAD_MB | No | Ceiling for one downloaded artefact | 512 |
| AINIZE_MCP_MAX_PER_PURCHASE | No | Ceiling for one purchase; defaults to the session budget | |
| AINIZE_MCP_ALLOW_AIN_PUBLISH | No | Also allow publish on a node whose ledger is the shared AIN chain; off by default | off |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Ainize — knowledge you can buy and knowledge you can teach, for a running LLM.
A knowledge is a trained memory-table patch a node applies into the serving model. The proof that one works is a before/after on the same question, not its description.
THE WORKFLOW, in order:
Before you claim a knowledge helps, PROVE IT — with ONE
live_testcall naming the candidate inknowledge. That call answers both columns itself, under one hold of the shared model lock, so nothing can move between them. Do NOT prove it with two calls: aknowledge: []call unloads nothing, so a knowledge another process left on the shared model answers along with the "base". Report both answers, the caveats, and who verified it with what score.Before you spend, QUOTE.
buycannot be called without aquote_idand the total restated exactly. Show the human the total, the base stack and the remaining session budget, and STOP. Never buy in the same turn you first learned the price.Before you teach, PREFLIGHT. A daily lesson is scarce and is not refunded — the node charges one the moment a lesson is submitted, whatever happens next. If the model already answers the questions, say so and do not submit.
teachdoes this for you and refuses withnothing_to_train; do not work around it.Everything that touches the model is a JOB. Call the tool, get a
job_id, polljob_status. If the model is held by another node,job_statussays who and for how long — report that instead of retrying in a loop.Never print or pass along a session token, teaching key, password or signature. This server holds them; you have no access and no need. No tool takes one.
Never background-poll a human decision. The turn that shows a price and asks for approval ENDS.
When something is not implemented, say so. Family-tree edge kinds, per-knowledge signals, bundle buys and merge are not built yet: the tools return
nulland a note. Report the note; do not invent the number.A vague request is a question, not a guess. If the price, the base or the knowledge is unspecified, ask.
TIERS: read freely (search_knowledge, get_knowledge, family_tree, get_training_set, node_status, my_library,
knowledge_signals, teacher_profile, quote, job_status, job_list). Echo back exactly what will happen and wait
for the human before anything that spends or mutates (buy, teach, apply_knowledge, remove_knowledge,
publish_knowledge). Two of those cannot be undone: buy moves real money, and publish_knowledge writes a
record on the ledger that nobody can recall.
THIS SERVER: node http://localhost:3422. Capabilities that are OFF right now:
can_live_test: off — the node reports no serving model (GET /api/runtime → available: false)
can_teach: off — no teaching key is configured on this MCP server (AINIZE_TEACH_KEY)
can_buy: off — no operator credential is configured on this MCP server (buying is operator-gated on the node)
can_apply: off — apply/remove change the model server every node on this machine shares — set AINIZE_MCP_ALLOW_APPLY=1 to enable them
can_publish: off — publishing is irreversible — set AINIZE_MCP_ALLOW_PUBLISH=1 (and AINIZE_MCP_ALLOW_AIN_PUBLISH=1 for a node on the shared AIN chain)
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_knowledgeA | Browse or search the knowledge this node and its peers sell: trained memory-table patches a node applies into a running LLM. Returns compact rows (id, name, price, rows, status, verification quorum, benchmark schema). Use this first when the model gave a wrong or outdated answer and you want to find something that fixes it. Free, no side effects. |
| get_knowledgeA | Everything about one knowledge: what it claims, who verified it and with what score, its family, the base stack it needs (requires[]), and whether this node already holds or bought it. Read this before quoting or live-testing. Free. |
| family_treeA | Ancestors, descendants and versions around one knowledge, walked from the ledger graph. Use it to see whether a cheaper parent or a newer version exists before buying. Free. |
| get_training_setA | Preview the questions and answers behind a training set — either the one a published knowledge was trained from (use it to judge whether a knowledge covers your question before paying) or one this teaching key uploaded with create_training_set (use it to show the human what actually landed before spending a lesson). Free. A |
| node_statusA | What this node is, whether the shared model is free and who holds it, what this MCP server is allowed to do (capabilities), the free live-test quota as last observed, and the teach policy. Call it when a job says the model is busy, or before spending anything. |
| my_libraryA | What this node already owns and what this teaching key already made: purchases (with tx hash and date), published knowledge, the applied stack, my teach jobs and my training sets. Check it before buying anything — a knowledge you already bought must never be bought twice. Free. |
| knowledge_signalsB | How much a knowledge has actually been used and scored, as far as THIS node can see: downloads, settlements, attestations and the recent event stream. Node-local and partial — per-day test/hit/miss counters exist in the node database but are not exposed by any endpoint yet. |
| teacher_profileA | A data provider's lessons and earnings on this node — who taught what, and what it paid them. Free. |
| job_statusA | Where a job started by live_test, teach, teach_preflight, apply_knowledge, remove_knowledge or buy has got to, and its result once it lands — for a lesson, that means what the model learned and what it did not. wait_ms long-polls inside this server (it does not hold a request open on the node), turning a poll loop into one call. Every answer says who holds the shared model and how many are waiting. A node lesson id works here too, so a conversation that lost its job_id is not stuck. |
| job_cancelA | Give up on a job. Cancelling a live test that is still QUEUED is genuinely free — nothing reached the model and no free try was consumed. Once it is running the work and the charge stand, and this tool says so instead of pretending otherwise. A buy that has already paid cannot be cancelled: use reconcile_purchase. |
| job_listA | The jobs this MCP session started, newest first — so a conversation that lost a job_id is not stuck. Jobs are evicted 30 minutes after they finish. |
| quoteA | What a knowledge really costs before anything moves: its price, whether it is verified and sellable, whether this node already bought it, the base stack it needs and the honest total with those bases, and how much session budget is left. Free and side-effect-light. This is the ONLY way to get a quote_id, and |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| instructions | The non-optional workflow: prove before you claim, quote before you spend, poll instead of blocking, never print a secret. |
| node | Identity, ledger, currency, serving model, capabilities and the session budget of the node this server speaks for. |
| budget | What this MCP session may still spend, and every purchase it has journalled. |
| openapi | The node's own OpenAPI document, for humans reading along. It is hand-written and misses the training-set routes — never generate tools from it. |
TDQS
Scored across 12 tools
Most tools have distinct read/action targets: search_knowledge (browse) vs get_knowledge (detail) vs family_tree (graph walk) vs knowledge_signals (usage) vs teacher_profile (provider) are separable by description, and the job_* trio splits cleanly into status/list/cancel. The main blur is quote vs get_knowledge (both take a knowledge id and both report stack/ownership) and my_library vs node_status, which overlap on node-local holdings and capabilities.
Conventions are mixed: verb_noun (search_knowledge, get_knowledge, get_training_set), noun_status compounds (job_status, node_status), and bare nouns (quote, family_tree, my_library, knowledge_signals, teacher_profile). Everything is snake_case and readable, but there is no predictable pattern an agent can rely on to guess a name.
12 tools sits in the healthy range and each of the twelve occupations (library, job status/cancel/list, quote, search, get, family tree, training set, node status, signals, teacher profile) is plausibly needed. It is slightly heavy on read-only inspection tools relative to the number of mutating operations actually exposed.
The descriptions repeatedly reference tools that do not exist in this surface: buy (explicitly required to follow quote), live_test, teach, teach_preflight, apply_knowledge, remove_knowledge, create_training_set, and reconcile_purchase. An agent can quote and inspect, but cannot actually complete the purchase/teach/live-test lifecycle the server is built around, leaving dead ends at the key decision points.