This server lets an agent answer questions from an organisation's own documents (with citations), inspect the corpus, and use a persistent memory store, all gated by read-only/read-write/admin modes.
Ask the documents – answer from internal policy, runbooks, handbooks, contracts or product docs, with exact passages as citations; refuses to guess when nothing supports an answer.
List namespaces – see the slices the corpus is divided into and how many documents each holds.
List documents – see what is available to answer from and whether uploads have finished ingesting.
Recall from memory – retrieve previously remembered facts/preferences relevant to the current situation, ranked by relevance, importance and recency; separate from the document corpus.
Add a document from a URL (read-write mode) – pull a public page into the corpus.
Remember (read-write mode) – record a preference, fact or decision worth keeping.
Forget a session (admin + explicit allow flag) – irreversibly erase one conversation's memory, with optional human confirmation.
Safety controls – read-only default, namespace allowlists/protected slices, dry-run writes, and audit logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ossian-mcp What does our handbook say about submitting expense reports?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Ossian — ask your organisation's own documents and get the passages the answer came from, plus a memory for your agent that outlives the conversation.
Ossian is the server; this is the adapter that puts it in front of an agent. You need a running
Ossian to point it at — see its README for a
docker compose up.
Tools are gated by access mode (see Safe by default) — the server starts read-only, exposing only the four read tools until you raise the mode.
Tool | For | Needs mode |
| answer from the corpus, with citations — and say so when it cannot | read-only |
| which slices exist, and how much is in each | read-only |
| what is available to answer from, and what is still ingesting | read-only |
| retrieve what is relevant now, ranked by relevance, importance and recency | read-only |
| pull a public page into the corpus | read-write |
| record a preference, fact or decision worth keeping | read-write |
| erase one conversation's memory (irreversible) | admin + |
Related MCP server: MCP Server + Document Memory System
npm install -g ossian-mcpYou need a running Ossian and an API key. Issue one from the console (Console → API keys) or:
curl -X POST "$OSSIAN_URL/api/admin/api-keys" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"mcp","roles":["ossian-user"],"namespace":"handbooks"}'Give the key the narrowest scope that works. namespace confines it to one slice, so a key that
leaks reads only what that agent was for.
{
"mcpServers": {
"ossian": {
"command": "ossian-mcp",
"env": {
"OSSIAN_URL": "http://localhost:8081",
"OSSIAN_API_KEY": "osk_...",
"OSSIAN_AGENT_ID": "support-bot",
"OSSIAN_MODE": "read-only"
}
}
}
}OSSIAN_AGENT_ID separates one agent's memories from another's; two agents sharing an id share
their recollections, which is occasionally what you want and usually not.
See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.
The server enforces an access model on top of the Ossian API key — defence in depth over the
key's own roles and namespace confinement. It reads its policy from the environment
(.env.example) and enforces it in src/security.ts:
OSSIAN_MODE — read-only (default) → read-write → admin. A tool is registered only if
the mode allows its capability. Read-only exposes four tools; ingest and remember need
read-write; forget needs admin.
OSSIAN_ALLOW_FORGET — forget_session erases memory irreversibly, so on top of admin
mode it also requires this flag.
OSSIAN_NAMESPACE_ALLOWLIST / OSSIAN_PROTECTED_NAMESPACES — confine which slices can be
touched, and mark slices that may be read but never ingested into.
OSSIAN_DRY_RUN — validate and log writes (ingest / remember / forget) without executing.
OSSIAN_AUDIT_LOG — a JSON audit line per guarded operation, on stderr (default on).
Interactive confirmation — when the client supports MCP elicitation, forget_session prompts the human to approve before erasing a session's memory; clients that can't elicit fall back to the OSSIAN_ALLOW_FORGET gate.
The primary control remains the API key: issue the narrowest one that works. See SECURITY.md.
A "not found" is an answer. ask_documents returns a refusal when nothing in the corpus
supports a response, and the tool description tells the model to report that rather than falling
back on general knowledge. An invented answer presented as company policy is the failure this
whole system exists to prevent — do not paper over it in your own prompt.
Memory is not the corpus. recall searches what the agent was told; ask_documents searches
what the organisation wrote down. They are separate stores on purpose: memories surfacing as
citations in a policy answer would be indistinguishable from the policy itself.
npm install
npm run build
OSSIAN_URL=http://localhost:8081 OSSIAN_API_KEY=osk_… node dist/index.jsIt speaks JSON-RPC over stdio, so it will sit there waiting for a frame. To drive it by hand:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.jsDiagnostics go to stderr on purpose — anything written to stdout that is not a protocol frame corrupts the stream, and the failure looks like a client that cannot parse rather than a server that printed a log line.
Apache-2.0
Answer a question from the organisation's own documents, with citations. Returns the exact passages the answer was written from. Use this for anything about internal policy, runbooks, handbooks, contracts or product documentation — anything the user's organisation wrote down. If nothing in the corpus supports an answer this reports that rather than guessing: treat 'not found' as the real answer and say so, do not fall back on general knowledge and present it as the organisation's policy.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The question, in full. Prefer the user's own wording. | |
| namespace | No | Narrow to one slice of the corpus, e.g. 'runbooks'. Omit to search everything. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavior: exact passages are returned and a 'not found' outcome is reported instead of a hallucinated answer, which materially changes how the agent should present results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action and citation behavior are front-loaded and every sentence carries information. The final sentence is slightly long with two imperatives stacked, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still covers what is returned (exact source passages) and the failure mode ('not found'), which is the information an agent most needs in order to relay results honestly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'question' and 'namespace' are fully documented in the schema. The description adds no parameter guidance (e.g. how to phrase the question or when to narrow with namespace), so this stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb-and-resource ('Answer a question from the organisation's own documents'), plus the output form ('with citations'). The scoping phrase 'anything the user's organisation wrote down' separates it from the sibling 'recall', which an agent would otherwise confuse with a document-QA tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use-case categories (internal policy, runbooks, handbooks, contracts, product documentation) and an implicit exclusion (don't use general knowledge). It never names the sibling tools (list_documents, recall, list_namespaces) as alternatives, so the routing is contextual rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the documents available to answer from, with their ingestion status. Use this to tell the user what the system actually knows about, or to check whether something they uploaded has finished processing.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Restrict to one namespace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that documents carry an ingestion/processing state, which is useful behavioral context, but it says nothing about permissions, volume, or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place: the first states what is returned, the second front-loads the use cases. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only list tool with no output schema, the description covers the key return concept (ingestion status) and usage intent, and annotations cover safety. Only minor gaps remain, such as pagination or result ordering for large document sets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'namespace' parameter is already documented as 'Restrict to one namespace.' The description adds no further meaning to it, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (documents) and adds scope ('available to answer from, with their ingestion status'). An agent can distinguish this from ask_documents (querying) and recall, though it does not explicitly name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete contexts for use: telling the user what the system knows about, and checking whether an upload finished processing. It does not name alternative tools or state when-not-to-use, so it stops short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the slices the document corpus is divided into, with how many documents each holds. Use this before ask_documents when a question clearly belongs to one area and you want to avoid another area answering it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the annotations (readOnly, idempotent, non-destructive) and does not contradict them. It does not describe return format or potential errors, but for a simple listing operation, annotations already convey safety and idempotency. The description adds minor behavioral context (document counts) but nothing that misleads the agent. Given the strong annotations, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences. The first sentence states what the tool does, and the second provides a usage guideline. There is no redundant wording or unnecessary detail. The structure is clear and front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a simple output (list of namespaces with counts), the description is complete. It states the action, the output content, and provides contextual guidance on when to use it. No output schema is provided, but the description implies a basic list structure. The tool's simplicity does not require further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to explain. The schema coverage is 100% with no required fields. The description correctly omits parameter details, and the baseline for no parameters is high. No additional parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing the slices (namespaces) of the document corpus along with document counts. It uses specific verbs ('List') and a concrete noun ('slices'), making the purpose unmistakable. It also differentiates from sibling tools by indicating when to use it ('before ask_documents'), which further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a usage condition: 'Use this before ask_documents when a question clearly belongs to one area and you want to avoid another area answering it.' This direct guidance tells the agent exactly when to choose this tool over ask_documents, fulfilling the requirement for clear usage instructions. It effectively addresses the alternative scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve what was previously remembered that relates to the current situation. Ranked by relevance, weighted by importance and decayed by age, so a recent statement outranks an old one saying the opposite. Worth calling at the start of a conversation with a returning user. This searches memory, not documents — use ask_documents for anything the organisation wrote down.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | What you are trying to recall, in natural language. | |
| agentId | No | ||
| subject | No | Narrow to one subject, e.g. 'user:ankit'. | |
| sessionId | No | Narrow to one conversation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely new behavioral context: results are ranked by relevance, weighted by importance, and decayed by age, so recency can override an older contradictory statement — this shapes how an agent should interpret and trust the results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler, with the core ranking behavior and the routing exclusion both front-loaded. Every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no output schema, the description covers purpose, timing, ranking semantics and sibling routing. It stops short of describing the shape or fields of a recalled memory item, and leaves limit/agentId unexplained, but overall it is sufficient to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%; query, subject and sessionId are documented in the schema but limit and agentId are bare, and the description adds no parameter-level detail such as how narrowing by subject/session interacts with ranking. With moderate coverage, the schema does most of the work and the description neither helps nor hurts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('retrieve') and resource ('what was previously remembered'), plus the retrieval model (relevance/importance/age ranking). It cleanly separates itself from ask_documents, which targets organisational documents rather than memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives both a positive trigger ('start of a conversation with a returning user') and an explicit alternative with its domain ('use ask_documents for anything the organisation wrote down'). An agent can decide without opening any schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.2ask_documents1 field changedInput schema / additionalPropertiesRemoved value: -falselist_documents1 field changedInput schema / additionalPropertiesRemoved value: -falserecall1 field changedInput schema / additionalPropertiesRemoved value: -falsev0.1.1ask_documentslist_documentslist_namespacesrecallScored across 4 tools
recall vs ask_documents is clearly delineated (memory vs organisational documents) and reinforced with explicit cross-references in the descriptions. list_documents and list_namespaces are both listing operations but target different resources (documents vs corpus slices with counts), so an agent should rarely confuse them.
Two tools follow a clean list_* pattern (list_documents, list_namespaces) and ask_documents uses a verb_noun form, but 'recall' is a bare verb with no object, breaking the pattern. The set is still readable, just not uniformly conventional.
Four tools is on the lean side but suits a narrow retrieval/memory scope where each tool earns its place. Nothing feels redundant or excessive for the stated purpose.
The read path is well covered (list documents, list namespaces, ask, recall), but there is no tool to store or update memories, and no way to fetch or inspect a single document. If ingestion is handled externally this is workable, but the memory side looks write-incomplete.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Document hosting and encrypted agent memory with multi-tenant persistence.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
