Skip to content
Sign in
On this page

Connect your Agent

Let your Agent look up what you saved in Mirabase, through MCP. You decide which spaces it can access and what it can do.

MCP address (Streamable HTTP)
text
https://api.mirabase.app/mcp

Quick start

  1. Connect your MCP client

    Enter the public MCP address and use Streamable HTTP transport.

  2. Sign in and authorize

    Sign in to Mirabase and choose the spaces and actions your Agent may use.

  3. Start using it

    Go back to your Agent and try finding something you saved. After you change authorization, reconnect.

Connect with a configuration file

json
{
  "mcpServers": {
    "mirabase": { "url": "https://api.mirabase.app/mcp", "transport": "streamable-http" }
  }
}

Connect your assistant

Every assistant uses the same address. Sign in to Mirabase, then choose the spaces it can use.

Cloud assistants

Claude (web and desktop)
  1. Open Settings › Connectors, click Add, then Add custom connector.

  2. Name it Mirabase and enter https://api.mirabase.app/mcp as the URL.

  3. Follow the prompts to sign in to Mirabase and choose the spaces Claude can use.

ChatGPT
  1. In ChatGPT on the web, open Plugins, click +, and choose Add custom MCP server. Whether you can add one depends on your ChatGPT plan and workspace settings.

  2. Name it Mirabase and paste https://api.mirabase.app/mcp under Connection. Choose OAuth for authentication and leave Client ID and Client Secret empty.

  3. Read the risk warning, check I understand and want to continue, then click Create as a plugin.

  4. Install the new plugin, sign in to Mirabase, and choose the spaces ChatGPT can use. Then start a new chat, type @, and choose Mirabase.

Grok
  1. Open grok.com/connectors, click New Connector, and choose Custom.

  2. Enter https://api.mirabase.app/mcp as the URL.

  3. Follow the prompts to sign in to Mirabase and choose the spaces Grok can use.

Muse Code
  1. In your settings file, add a streamable_http entry under mcp_servers with https://api.mirabase.app/mcp as the URL.

  2. Run the command below to sign in to Mirabase and choose spaces. The Muse app itself doesn't support custom MCP yet.

bash
muse mcp login mirabase

Local Agents

Claude Code
  1. Run the command below, then type /mcp in Claude Code and choose mirabase to sign in.

bash
claude mcp add --transport http --scope user mirabase https://api.mirabase.app/mcp
Codex
  1. Run the two commands below in order. The second opens your browser to sign in to Mirabase.

bash
codex mcp add mirabase --url https://api.mirabase.app/mcp
bash
codex mcp login mirabase
Cursor and other editors
  1. Add the configuration file above to its MCP settings. With Mirabase for Mac, one click on its Connect page does it.

Any other assistant that supports remote MCP (Streamable HTTP) with OAuth sign-in can connect with the same address. Assistants that only accept an API key can't connect yet.

Manage access

In the account center, you can see your Agent connections, change the spaces and actions they're allowed, or revoke access at any time.

Use your MCP client's own sign-in and authorization. Don't put long-lived credentials in its configuration.

Go to the account center →

Questions

Connected, but can't find anything?

Check that the item has finished processing and that its space is authorized for this Agent. After you change authorization, reconnect and refresh the tool list.

Asked to sign in, or told you don't have permission?

401 usually means your sign-in expired. Reconnect. 403 means the current authorization doesn't allow this action. Check the spaces and tool permissions you chose.

How do I stop an Agent's access?

Revoke it under Agent connections in the account center. After that, the connection can no longer access your library.

MCP tool reference

The tools and parameters you can use are what tools/list returns after you connect. The examples below match reference version v0.6.10.

Example call
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "mira.recall", "arguments": { "query": "When is the launch window?", "scope": { "space_ids": ["spc_product"] } } }
}

mira.read

Permission: knowledge:readAvailable by default

Read one authorized Entry. Available by default.

Parameters

Swipe sideways to see every parameter
ParameterTypeDescription
inputRequiredReadEntryInputThe input schema returned by MCP tools/list; field constraints are generated from the canonical contract.

Response

TypeReadEntryPayload
json
{
  "structuredContent": {
    "entry": {
      "entry_id": "example",
      "space_id": "resource_01",
      "tier": "knowledge",
      "source_type": "example",
      "title": "example",
      "canonical_url": "example",
      "current_version_id": "example",
      "latest_version_id": "example",
      "processing_status": "accepted",
      "created_at": "2026-08-27T00:00:00Z",
      "updated_at": "2026-08-27T00:00:00Z"
    }
  }
}

Error responses

mira.recall

Permission: knowledge:readAvailable by default

Search your saved knowledge. Available by default.

Parameters

Swipe sideways to see every parameter
ParameterTypeDescription
inputRequiredRecallRequestThe input schema returned by MCP tools/list; field constraints are generated from the canonical contract.

Response

TypeRecallPayload
json
{
  "structuredContent": {
    "results": [
      {
        "entry_id": "example",
        "version_id": "example",
        "chunk_id": "example",
        "snippet": "example",
        "locator": {
          "type": "heading",
          "heading_path": [
            "example"
          ]
        },
        "source_type": "example"
      }
    ],
    "partial": false,
    "trace_id": "example"
  }
}

Error responses

mira.memory_candidate

Permission: memory:candidateNeeds extra authorization

Propose a memory candidate without writing to a Space directly. Requires separate authorization.

Parameters

Swipe sideways to see every parameter
ParameterTypeDescription
inputRequiredCreateMemoryCandidateRequestThe input schema returned by MCP tools/list; field constraints are generated from the canonical contract.

Response

TypeMemoryCandidate
json
{
  "structuredContent": {
    "candidate_id": "example",
    "title": "example",
    "content": "example",
    "status": "candidate",
    "created_at": "2026-08-27T00:00:00Z"
  }
}

Error responses

mira.confirm_memory_candidate

Permission: memory:confirmNeeds extra authorization

Confirm a memory candidate and send it through asynchronous processing. Requires separate authorization.

Parameters

Swipe sideways to see every parameter
ParameterTypeDescription
inputRequiredConfirmMemoryCandidateInputThe input schema returned by MCP tools/list; field constraints are generated from the canonical contract.

Response

TypeAcceptedEntryReceipt
json
{
  "structuredContent": {
    "entry_id": "example",
    "version_id": "example",
    "job_id": "example",
    "status": "accepted"
  }
}

Error responses

mira.write

Permission: knowledge:writeNeeds extra authorization

Separately authorized tool for writing knowledge.

Parameters

Swipe sideways to see every parameter
ParameterTypeDescription
inputRequiredCreateEntryRequestThe input schema returned by MCP tools/list; field constraints are generated from the canonical contract.

Response

TypeAcceptedEntryReceipt
json
{
  "structuredContent": {
    "entry_id": "example",
    "version_id": "example",
    "job_id": "example",
    "status": "accepted"
  }
}

Error responses

mira.manage

Permission: knowledge:manageNeeds extra authorization

Separately authorized governance tool. Every organizing action requires knowledge:manage.

Parameters

Swipe sideways to see every parameter
ParameterTypeDescription
inputRequiredMcpTools.ManageInputThe input schema returned by MCP tools/list; field constraints are generated from the canonical contract.

Response

TypeMcpTools.ManageResult
json
{
  "structuredContent": {
    "entry_id": "example",
    "deletion_status": "tombstoned",
    "cleanup_job_id": "example"
  }
}

Error responses

MCP reference

Error codes

The HTTP status tells you the kind of error, and the error code tells you the cause. Keep the request_id for troubleshooting.

HTTP statusError codeDescription
400invalid_requestThe request body isn't valid JSON, the Content-Type doesn't match, or a required field is missing or has the wrong type.
401unauthorizedThe Authorization header is missing, or the OIDC JWT is invalid, expired, or revoked, or its issuer or audience doesn't match.
402quota_exceededThe account or space has used up its quota.
403forbiddenThe caller lacks access to the target Space or Source, or the capability the operation requires.
404not_foundThe target entry_id, source_id or space_id doesn't exist, isn't accessible to the caller, or has been cleaned up (tombstoned).
409conflictThe resource is in a conflicting state. For example, the revision doesn't match, or the entry was merged or superseded by a newer version.
409resource_busyThe resource is being processed in the background and can't be changed right now. Try again later.
413payload_too_largeThe content or uploaded file is over the size limit for one request. Split it up, or use asynchronous upload.
415unsupported_media_typeThe file format, character encoding, or encryption can't be parsed yet.
422validation_errorA field failed semantic validation. The field value in the response names the first invalid field.
429rate_limitedToo many requests, or too many at once. Back off and retry as Retry-After says. Every response includes X-RateLimit-Limit / Remaining / Reset.
500internal_errorSomething went wrong inside the service. Keep the request_id from the response for troubleshooting.
502dependency_errorAn upstream service responded abnormally, so the request couldn't complete.
503service_unavailableThe service is temporarily unavailable, for example while a model loads, an index rebuilds or a node is under maintenance. Back off and retry as Retry-After says.
504timeoutRetrieval or answer generation timed out. Try again with a smaller depth or top_k.

Interested in the knowledge infrastructure?

If you want to use the Mirabase Data Layer in your own product, tell us about your use case.

Contact us