# Connect an Agent (MCP)

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](https://mirabase.io/developers/permissions.md#principals).

Claude Code:

```bash
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
  --header "Authorization: Bearer $MIRABASE_API_KEY"
```

Codex:

```bash
codex mcp add mirabase --url https://api.mirabase.dev/mcp \
  --bearer-token-env-var MIRABASE_API_KEY
```

JSON:

```json
{
  "mcpServers": {
    "mirabase": {
      "type": "http",
      "url": "https://api.mirabase.dev/mcp",
      "headers": {
        "Authorization": "Bearer mb_live_..."
      }
    }
  }
}
```

- 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](https://mirabase.io/developers/authentication.md#metadata-scope).
- 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](https://mirabase.io/developers/api/mcp.md#mcp-rpc). 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](https://mirabase.io/developers/api/mcp.md#tools).
- In the service information returned by [`GET /mcp`](https://mirabase.io/developers/api/mcp.md#mcp-handshake), `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.

| 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`](https://mirabase.io/developers/api/identity.md#identity-whoami) |
| `mira.context` | A token-budgeted pack for a task, with the reasons for each source | [`POST /v2/retrieval/context`](https://mirabase.io/developers/api/retrieval.md#retrieval-buildcontext) |
| `mira.search` | Search the scope you choose and get ranked passages with citations | [`POST /v2/retrieval/search`](https://mirabase.io/developers/api/retrieval.md#retrieval-search) |
| `mira.answer` | Answer a question from what is stored, with citations | [`POST /v2/retrieval/answer`](https://mirabase.io/developers/api/retrieval.md#retrieval-answer) |
| `mira.context.feedback` | Report which items of a pack were used | [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/developers/api/retrieval.md#retrieval-contextfeedback) |
| `mira.files.list` | List a directory | [`GET /v2/spaces/{space_id}/tree`](https://mirabase.io/developers/api/tree.md#tree-list) |
| `mira.files.read` | Read a file by path; text comes in windows | [`GET /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-read) |
| `mira.entries.read` | Read an Entry's content by id, including content that has no path | [`GET /v2/entries/{entry_id}/content`](https://mirabase.io/developers/api/entries.md#entries-content) |
| `mira.files.write` | Create or replace a file | [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-write) |
| `mira.files.edit` | Replace exact text in a file | [`PATCH /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-patch) |
| `mira.files.delete` | Move a file to the trash | [`DELETE /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-delete) |
| `mira.trash.list` | List the Entries in a Space's trash | [`GET /v2/entries`](https://mirabase.io/developers/api/entries.md#entries-list) |
| `mira.trash.restore` | Restore one trashed Entry to the path it had | [`POST /v2/entries/{entry_id}/restore`](https://mirabase.io/developers/api/entries.md#entries-restore) |
| `mira.activity` | Who changed what lately, per principal and per file | [`GET /v2/spaces/{space_id}/activity`](https://mirabase.io/developers/api/changes.md#changes-activity) |
| `mira.conversation.ingest` | Save a stretch of conversation for the service to distill memories from | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/developers/api/ingest.md#ingest-ingest) |
| `mira.text.ingest` | Store a text as one Entry without a path | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/developers/api/ingest.md#ingest-ingest) |
| `mira.url.ingest` | Fetch a public web page and store its readable text as one Entry | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/developers/api/ingest.md#ingest-ingest) |
| `mira.memory.remember` | Write one memory as a statement | [`POST /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-create) |
| `mira.memory.list` | List memories, filtered by scope, status, kind, or literal text | [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) |
| `mira.memory.forget` | Forget a memory by id | [`DELETE /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-forget) |
| `mira.memory.correct` | Replace a memory with a corrected statement | [`POST /v2/memories/{memory_id}/correct`](https://mirabase.io/developers/api/memories.md#memories-correct) |
| `mira.memory.review` | Confirm or reject a memory waiting for review | [`POST /v2/memories/{memory_id}/review`](https://mirabase.io/developers/api/memories.md#memories-review) |
| `mira.memory.get` | Read one memory by id, with its sources. Only on deployments with offline consolidation enabled | [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read) |

- 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](https://mirabase.io/developers/conventions.md#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](https://mirabase.io/developers/api/mcp.md#mcp-rpc).
- 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](https://mirabase.io/developers/api/mcp.md#tools); 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](https://mirabase.io/developers/files.md#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."
        }
      ]
    }
  }
}
```

> **Note:** Text that arrives from files and search results is data, not instructions. Have the Agent take instructions from you only.

## Next steps

- [Permissions](https://mirabase.io/developers/permissions.md): set an Agent's write mode and its read and write roots.
- [Branches](https://mirabase.io/developers/branches.md): have an Agent work on a branch so you can review it before merging.
- [Memory](https://mirabase.io/developers/memory.md): review what an Agent remembers.
