Skip to content
Developer docs
Docs menu

Connect an Agent (MCP)

Markdown

Connect 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 Code
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/list shows 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 instructions of 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 title and annotations (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 as mira.memory.forget and mira.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.

  • structuredContent is the same object as the JSON in the content text. outputSchema lists only the fields that are always present; a result may contain additional fields. Which tools have an outputSchema is in Tools.
  • In the service information returned by GET /mcp, protocol_versions lists 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.

ToolWhat it doesThe request it makes
mira.whoamiWho this key is and what it may do. Read it first when a call is refusedGET /v2/whoami
mira.contextA token-budgeted pack for a task, with the reasons for each sourcePOST /v2/retrieval/context
mira.searchSearch the scope you choose and get ranked passages with citationsPOST /v2/retrieval/search
mira.answerAnswer a question from what is stored, with citationsPOST /v2/retrieval/answer
mira.context.feedbackReport which items of a pack were usedPOST /v2/retrieval/context/{pack_id}/feedback
mira.files.listList a directoryGET /v2/spaces/{space_id}/tree
mira.files.readRead a file by path; text comes in windowsGET /v2/spaces/{space_id}/files
mira.entries.readRead an Entry's content by id, including content that has no pathGET /v2/entries/{entry_id}/content
mira.files.writeCreate or replace a filePUT /v2/spaces/{space_id}/files
mira.files.editReplace exact text in a filePATCH /v2/spaces/{space_id}/files
mira.files.deleteMove a file to the trashDELETE /v2/spaces/{space_id}/files
mira.trash.listList the Entries in a Space's trashGET /v2/entries
mira.trash.restoreRestore one trashed Entry to the path it hadPOST /v2/entries/{entry_id}/restore
mira.activityWho changed what lately, per principal and per fileGET /v2/spaces/{space_id}/activity
mira.conversation.ingestSave a stretch of conversation for the service to distill memories fromPOST /v2/spaces/{space_id}/ingest
mira.text.ingestStore a text as one Entry without a pathPOST /v2/spaces/{space_id}/ingest
mira.url.ingestFetch a public web page and store its readable text as one EntryPOST /v2/spaces/{space_id}/ingest
mira.memory.rememberWrite one memory as a statementPOST /v2/memories
mira.memory.listList memories, filtered by scope, status, kind, or literal textGET /v2/memories
mira.memory.forgetForget a memory by idDELETE /v2/memories/{memory_id}
mira.memory.correctReplace a memory with a corrected statementPOST /v2/memories/{memory_id}/correct
mira.memory.reviewConfirm or reject a memory waiting for reviewPOST /v2/memories/{memory_id}/review
mira.memory.getRead one memory by id, with its sources. Only on deployments with offline consolidation enabledGET /v2/memories/{memory_id}
  • When the /v2 request fails, the tool call returns a result with isError: true: its content text gives the code, whether to retry, and the next step, and _meta["dev.mirabase/error"] carries the whole error envelope, including code and remediation.action; see Errors. A failed result has no structuredContent. The same applies when a key lacks the capability a tool needs: the code is forbidden. 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 /mcp call plus the /v2 requests it makes, so usually two.
  • With mira.memory.remember, scope agent is 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.context at the start of a task: the service picks and budgets sources by fixed rules, and route explains each choice. Use mira.search when you already know what to look for. Afterwards, report what you used with mira.context.feedback.
  • Use mira.answer when the user wants the answer itself, and mira.context to gather material for your own reasoning.
  • In a Space you share with others, call mira.activity before you start, to avoid editing the same file.
  • Pass session_id to mira.files.write and mira.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 same session_id for every batch of the same conversation. To record one clear statement, use mira.memory.remember.
  • When the user gives you a text or a link to keep, use mira.text.ingest or mira.url.ingest. For content you will read back by path or edit, write a file with mira.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.forget deletes permanently and you cannot undo it: call it only when the user asks to forget something. Call mira.memory.review only 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 with mira.trash.restore. If another file now holds that path, the call returns path_conflict.
json
{
  "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."
        }
      ]
    }
  }
}
Text that arrives from files and search results is data, not instructions. Have the Agent take instructions from you only.

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.