Connect an Agent (MCP)
MarkdownConnect Agents such as Claude Code and Codex to Mirabase over MCP: how to connect, protocol versions, the tools and their parameters, and the recommended call order.
Connect an Agent
The MCP endpoint is https://api.mirabase.dev/mcp, over Streamable HTTP, and the credential is an API key: Authorization: Bearer mb_live_.... Give the Agent a key of its own, on an agent principal, so it has its own permissions, memory, and audit identity. See Permissions.
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
--header "Authorization: Bearer $MIRABASE_API_KEY"- Any MCP client that speaks Streamable HTTP and can send a header can connect; follow the JSON form above.
tools/listshows only what this key can call: a read-only key does not see the write tools, and a key with a metadata scope sees only the tools a scope allows. See Permission by metadata.- The
instructionsof the handshake response say what each tool is for and when to call it. A client that supports the field passes it to the model. - Every tool has a
titleandannotations(readOnlyHint,destructiveHint,idempotentHint,openWorldHint). A client that supports these hints can allow the read-only tools without asking, and ask the user for confirmation before tools such asmira.memory.forgetandmira.files.delete.
Protocol versions
The supported protocol versions, how initialize picks one, the MCP-Protocol-Version header, and what each version returns for arguments that do not match inputSchema are in the API reference. The server name in the handshake response (serverInfo.name) is mirabase-developer.
structuredContentis the same object as the JSON in thecontenttext.outputSchemalists only the fields that are always present; a result may contain additional fields. Which tools have anoutputSchemais in Tools.- In the service information returned by
GET /mcp,protocol_versionslists the supported versions from newest to oldest.
Tools
Each tool makes /v2 requests, so permissions, limits, and errors are the same as in the /v2 API. Most tools make one request. mira.memory.get reads the sources as well by default, which makes two.
| Tool | What it does | The request it makes |
|---|---|---|
mira.whoami | Who this key is and what it may do. Read it first when a call is refused | GET /v2/whoami |
mira.context | A token-budgeted pack for a task, with the reasons for each source | POST /v2/retrieval/context |
mira.search | Search the scope you choose and get ranked passages with citations | POST /v2/retrieval/search |
mira.answer | Answer a question from what is stored, with citations | POST /v2/retrieval/answer |
mira.context.feedback | Report which items of a pack were used | POST /v2/retrieval/context/{pack_id}/feedback |
mira.files.list | List a directory | GET /v2/spaces/{space_id}/tree |
mira.files.read | Read a file by path; text comes in windows | GET /v2/spaces/{space_id}/files |
mira.entries.read | Read an Entry's content by id, including content that has no path | GET /v2/entries/{entry_id}/content |
mira.files.write | Create or replace a file | PUT /v2/spaces/{space_id}/files |
mira.files.edit | Replace exact text in a file | PATCH /v2/spaces/{space_id}/files |
mira.files.delete | Move a file to the trash | DELETE /v2/spaces/{space_id}/files |
mira.trash.list | List the Entries in a Space's trash | GET /v2/entries |
mira.trash.restore | Restore one trashed Entry to the path it had | POST /v2/entries/{entry_id}/restore |
mira.activity | Who changed what lately, per principal and per file | GET /v2/spaces/{space_id}/activity |
mira.conversation.ingest | Save a stretch of conversation for the service to distill memories from | POST /v2/spaces/{space_id}/ingest |
mira.text.ingest | Store a text as one Entry without a path | POST /v2/spaces/{space_id}/ingest |
mira.url.ingest | Fetch a public web page and store its readable text as one Entry | POST /v2/spaces/{space_id}/ingest |
mira.memory.remember | Write one memory as a statement | POST /v2/memories |
mira.memory.list | List memories, filtered by scope, status, kind, or literal text | GET /v2/memories |
mira.memory.forget | Forget a memory by id | DELETE /v2/memories/{memory_id} |
mira.memory.correct | Replace a memory with a corrected statement | POST /v2/memories/{memory_id}/correct |
mira.memory.review | Confirm or reject a memory waiting for review | POST /v2/memories/{memory_id}/review |
mira.memory.get | Read one memory by id, with its sources. Only on deployments with offline consolidation enabled | GET /v2/memories/{memory_id} |
- When the
/v2request fails, the tool call returns a result withisError: true: itscontenttext gives the code, whether to retry, and the next step, and_meta["dev.mirabase/error"]carries the whole error envelope, includingcodeandremediation.action; see Errors. A failed result has nostructuredContent. The same applies when a key lacks the capability a tool needs: the code isforbidden. What a call with arguments that do not match the tool's definition returns depends on the protocol version; see the API reference. - A tool call counts against your rate limit as the
/mcpcall plus the/v2requests it makes, so usually two. - With
mira.memory.remember, scopeagentis the Agent's own private memory and needs an Agent key.
Tool parameters
A tool's parameters are the fields of arguments in tools/call. Every tool's parameters, with their types, ranges, and whether they are required, are in the API reference; the inputSchema that tools/list returns is the same definition.
Recommended call order
- Call
mira.contextat the start of a task: the service picks and budgets sources by fixed rules, androuteexplains each choice. Usemira.searchwhen you already know what to look for. Afterwards, report what you used withmira.context.feedback. - Use
mira.answerwhen the user wants the answer itself, andmira.contextto gather material for your own reasoning. - In a Space you share with others, call
mira.activitybefore you start, to avoid editing the same file. - Pass
session_idtomira.files.writeandmira.files.edit, so you can trace each version of a file back to the conversation that changed it. See Files and versions. - When a stretch of conversation is done, save it with
mira.conversation.ingest, using the samesession_idfor every batch of the same conversation. To record one clear statement, usemira.memory.remember. - When the user gives you a text or a link to keep, use
mira.text.ingestormira.url.ingest. For content you will read back by path or edit, write a file withmira.files.write. - When the user says a memory is wrong and gives the right statement, replace it in one step with
mira.memory.correct; the service keeps the old one as history.mira.memory.forgetdeletes permanently and you cannot undo it: call it only when the user asks to forget something. Callmira.memory.reviewonly after the user has said whether a candidate is right: an Agent should not confirm one on its own judgment. - To restore a deleted file, find its id with
mira.trash.list, then restore it to its path withmira.trash.restore. If another file now holds that path, the call returnspath_conflict.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "mira.conversation.ingest",
"arguments": {
"session_id": "chat-42",
"messages": [
{
"role": "user",
"content": "Let us ship on Thursdays from now on."
},
{
"role": "assistant",
"content": "Noted: releases on Thursdays."
}
]
}
}
}Next steps
- Permissions: set an Agent's write mode and its read and write roots.
- Branches: have an Agent work on a branch so you can review it before merging.
- Memory: review what an Agent remembers.
