> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Expose Memanto's persistent semantic memory to any MCP-compatible client (Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, …) with a single config line.

# Model Context Protocol (MCP)

<img src="https://mintcdn.com/memanto/II1GP7bpRVzYh2QP/logo/integrations/mcp.png?fit=max&auto=format&n=II1GP7bpRVzYh2QP&q=85&s=7894020ed206c441577611a85e89ea8b" alt="mcp" width="140" style={{marginBottom: "1.5rem"}} data-path="logo/integrations/mcp.png" />

The [`memanto-mcp`](https://pypi.org/project/memanto-mcp/) package exposes Memanto's memory primitives — `remember`, `recall`, `answer`, and friends — as [Model Context Protocol](https://modelcontextprotocol.io) tools, so any MCP-compatible client can plug into long-term memory in a **single config line**.

> One Moorcheh API key → typed semantic memory shared across every agent that uses the namespace, with sub-90 ms retrieval, conflict detection, and zero ingestion latency.

<CardGroup cols={2}>
  <Card title="Universal" icon="plug">
    Works with every MCP host: Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, Codex, and custom agents using the MCP SDK.
  </Card>

  <Card title="Zero glue code" icon="bolt">
    No client code, no vector DB. Add one JSON block to your client's config and the agent gets 7 memory tools.
  </Card>

  <Card title="Typed memory" icon="layer-group">
    13 memory types (fact, preference, decision, goal, instruction, …) with confidence + provenance — built for LLM tool-selection.
  </Card>

  <Card title="Shared namespace" icon="users">
    Different clients pointed at the same `agent_id` share one memory. Remember in Claude Desktop, recall in Cursor.
  </Card>
</CardGroup>

## How It Works

```
┌──────────────┐    MCP (stdio)    ┌──────────────────┐    HTTPS + API key   ┌─────────────┐
│ Claude / IDE │ ────────────────► │   memanto-mcp    │ ───────────────────► │   Moorcheh  │
│   (client)   │ ◄──────────────── │   (this server)  │ ◄─────────────────── │   Service   │
└──────────────┘   tool calls      └──────────────────┘   no-indexing search └─────────────┘
```

The server runs locally next to your MCP host. On the first tool call it activates a Memanto session (auto-creating the agent if needed) and reuses it across the conversation. Sessions auto-renew before expiry, so long-running MCP connections never hit a session-expired error mid-turn.

## Prerequisites

* Python **3.10+**
* A [Moorcheh API key](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month)
* Any MCP-compatible client

## Install

```bash theme={null}
pip install memanto-mcp
```

This installs the `memanto-mcp` console script that every client below launches over stdio.

## Quickstart

Pick your client. The JSON shape is identical across most hosts — only the config file path changes.

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open the config file">
        * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

        Or use **Settings → Developer → Edit Config**.
      </Step>

      <Step title="Add the Memanto server">
        ```json theme={null}
        {
          "mcpServers": {
            "memanto": {
              "command": "memanto-mcp",
              "env": {
                "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
                "MEMANTO_DEFAULT_AGENT_ID": "my-assistant"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Ask Claude to *"remember that I prefer concise answers"*. Tomorrow, in a brand-new chat, ask *"what do I prefer?"* — the answer comes from Memanto.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open the config file">
        * **Per-user**: `~/.cursor/mcp.json`
        * **Per-project**: `.cursor/mcp.json` (committable)
      </Step>

      <Step title="Add the Memanto server">
        ```json theme={null}
        {
          "mcpServers": {
            "memanto": {
              "command": "memanto-mcp",
              "env": {
                "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
                "MEMANTO_DEFAULT_AGENT_ID": "cursor-workspace"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload Cursor">
        Open the MCP panel and confirm `memanto` shows up with **7 tools**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    Edit `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "memanto": {
          "command": "memanto-mcp",
          "env": {
            "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
            "MEMANTO_DEFAULT_AGENT_ID": "windsurf-workspace"
          }
        }
      }
    }
    ```

    Reload Windsurf via **Cascade → MCP Servers → Refresh**.
  </Tab>

  <Tab title="Cline (VS Code)">
    Edit `cline_mcp_settings.json` (path depends on OS):

    * **Linux**: `~/.config/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
    * **macOS**: `~/Library/Application Support/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
    * **Windows**: `%APPDATA%\Code\User\globalStorage\cline.cline\settings\cline_mcp_settings.json`

    ```json theme={null}
    {
      "mcpServers": {
        "memanto": {
          "command": "memanto-mcp",
          "env": {
            "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
            "MEMANTO_DEFAULT_AGENT_ID": "cline-workspace"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Continue">
    Edit `~/.continue/config.json`:

    ```json theme={null}
    {
      "experimental": {
        "modelContextProtocolServers": [
          {
            "transport": {
              "type": "stdio",
              "command": "memanto-mcp",
              "env": {
                "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
                "MEMANTO_DEFAULT_AGENT_ID": "continue-workspace"
              }
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Goose">
    Edit `~/.config/goose/config.yaml`:

    ```yaml theme={null}
    extensions:
      memanto:
        type: stdio
        command: memanto-mcp
        envs:
          MOORCHEH_API_KEY: mch_xxxxxxxxxxxxxxxxxx
          MEMANTO_DEFAULT_AGENT_ID: goose-workspace
    ```
  </Tab>
</Tabs>

<Note>
  The first call auto-creates the `MEMANTO_DEFAULT_AGENT_ID` namespace and activates a session. Every subsequent call (in any client pointed at the same agent) reuses the same persistent memory.
</Note>

## Available Tools

The server registers **7 memory tools** by default. Set `MEMANTO_EXPOSE_ADMIN=true` to also expose **4 agent-management tools**.

### Memory tools (always on)

| Tool                   | When the agent should call it                                                         |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `remember`             | Persist a single fact, preference, decision, goal, or instruction.                    |
| `batch_remember`       | Persist up to 100 memories in one call (e.g. extracted from a document).              |
| `recall`               | Semantic search — **always** check here before asking the user to repeat stable info. |
| `recall_recent`        | *"What did we just decide?"* — newest-first, no query needed.                         |
| `recall_as_of`         | Point-in-time recall — *"what did we know on 2025-11-01?"*                            |
| `recall_changed_since` | Differential recall — *"what's new since I last checked?"*                            |
| `answer`               | RAG: a grounded LLM answer synthesized over the agent's memories.                     |

### Agent admin tools (opt-in)

Enabled when `MEMANTO_EXPOSE_ADMIN=true`:

| Tool           | Purpose                               |
| -------------- | ------------------------------------- |
| `create_agent` | Create a new memory namespace.        |
| `list_agents`  | List every agent the API key can see. |
| `get_agent`    | Look up an agent's metadata.          |
| `delete_agent` | Remove an agent's local metadata.     |

<AccordionGroup>
  <Accordion title="Memory types accepted by remember / batch_remember">
    `fact`, `preference`, `goal`, `decision`, `artifact`, `learning`, `event`, `instruction`, `relationship`, `context`, `observation`, `commitment`, `error`.

    See the [Memory Types Reference](/reference/memory-types) for guidance on picking the right type.
  </Accordion>

  <Accordion title="Provenance values">
    `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`.

    Use `explicit_statement` when the user said it directly, `inferred` when you deduced it, and `corrected` when overriding an earlier wrong memory.
  </Accordion>

  <Accordion title="Fields returned by recall">
    Each memory hit from `recall` / `recall_recent` / `recall_as_of` / `recall_changed_since` carries its trust and provenance metadata:

    * `id`, `title`, `content`, `type`, `confidence`, `score`, `created_at`, `tags`
    * `status` — lifecycle state (`active`, `superseded`, …).
    * `source` — where the memory came from: `user`, `agent`, or the uploaded file name.
    * `source_ref` — pointer to the original record within that source (e.g. tool-call or migration id). `null` when not set.
    * `provenance` — how the memory was obtained (`explicit_statement`, `inferred`, …).
  </Accordion>
</AccordionGroup>

## Configuration

All configuration is via environment variables (load order: process env → `.env` file in the working directory). Most clients let you set these inside the `env` block of the MCP server entry.

| Variable                         |   Required  | Default     | Description                                                                         |
| -------------------------------- | :---------: | ----------- | ----------------------------------------------------------------------------------- |
| `MOORCHEH_API_KEY`               |   **yes**   | —           | Moorcheh API key.                                                                   |
| `MEMANTO_DEFAULT_AGENT_ID`       | recommended | —           | Default agent. When set, tool calls may omit `agent_id`.                            |
| `MEMANTO_AGENT_PATTERN`          |      no     | `tool`      | Pattern (`support` / `project` / `tool`) used when auto-creating the default agent. |
| `MEMANTO_AGENT_AUTO_CREATE`      |      no     | `true`      | Create the default agent on first use if missing.                                   |
| `MEMANTO_SESSION_DURATION_HOURS` |      no     | `6`         | Session lifetime in hours (1 – 720).                                                |
| `MEMANTO_EXPOSE_ADMIN`           |      no     | `false`     | Register the 4 agent-management tools.                                              |
| `MEMANTO_MCP_TRANSPORT`          |      no     | `stdio`     | `stdio`, `sse`, or `streamable-http`.                                               |
| `MEMANTO_MCP_HOST`               |      no     | `127.0.0.1` | Bind host for sse / http transports.                                                |
| `MEMANTO_MCP_PORT`               |      no     | `8765`      | Bind port for sse / http transports.                                                |
| `MEMANTO_MCP_LOG_LEVEL`          |      no     | `INFO`      | Log level. Logs are always sent to stderr.                                          |

CLI flags override env vars:

```bash theme={null}
memanto-mcp --transport sse --port 9000 --log-level DEBUG
```

## Running over HTTP / SSE

For remote clients or multi-process setups, run the server over a network transport:

<Tabs>
  <Tab title="Streamable HTTP (recommended)">
    ```bash theme={null}
    memanto-mcp --transport streamable-http --host 0.0.0.0 --port 8765
    ```

    Point your client at `http://your-host:8765/mcp`.
  </Tab>

  <Tab title="SSE (legacy)">
    ```bash theme={null}
    memanto-mcp --transport sse --host 0.0.0.0 --port 8765
    ```

    Older transport, still widely supported.
  </Tab>
</Tabs>

<Warning>
  The server authenticates **upstream** to Moorcheh with your API key, but does **not** authenticate inbound MCP clients. For production, pair it with a reverse proxy that enforces auth (e.g. mTLS, OAuth, or a shared bearer token).
</Warning>

## Programmatic Embedding

Wiring the server into a larger Python process or custom MCP host:

```python theme={null}
from memanto_mcp import MCPServerSettings, build_server

settings = MCPServerSettings()  # reads env / .env
mcp = build_server(settings)

# Add your own tools alongside Memanto's, then run.
mcp.run(transport="stdio")
```

Useful when you want to combine Memanto with a domain-specific MCP toolset in one process.

## Sharing Memory Across Clients

Point multiple clients at the **same** `MEMANTO_DEFAULT_AGENT_ID` and they share one persistent memory namespace:

```json theme={null}
// Claude Desktop
"env": { "MEMANTO_DEFAULT_AGENT_ID": "my-personal" }

// Cursor
"env": { "MEMANTO_DEFAULT_AGENT_ID": "my-personal" }
```

A preference stored in Claude Desktop is now recallable from Cursor on the next tool call — Moorcheh's no-indexing search means the memory is queryable the millisecond it's written.

## Troubleshooting

| Symptom                                                              | Fix                                                                                                                                                    |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `configuration error: MOORCHEH_API_KEY is required`                  | Set the env var in your MCP client config's `env` block.                                                                                               |
| `Agent '…' does not exist and MEMANTO_AGENT_AUTO_CREATE is disabled` | Re-enable auto-create, or call `create_agent` (admin tools) / `memanto agent create <id>` once.                                                        |
| Tools never appear in the client                                     | Confirm the client supports MCP and the config path matches. Check the client's MCP log: `memanto_mcp` lines on startup come from this server.         |
| Garbled output in stdio mode                                         | Something on your side is writing to **stdout** — that channel is reserved for JSON-RPC. Move logs to stderr. The server itself only writes to stderr. |
| Slow first call                                                      | Cold-start cost: SDK import + first session activation. Subsequent calls reuse the live session.                                                       |
| Session-expired errors mid-conversation                              | The server auto-renews before expiry. If you still see this, bump `MEMANTO_SESSION_DURATION_HOURS`.                                                    |

## Next Steps

<CardGroup cols={2}>
  <Card title="Memory Types Reference" icon="layer-group" href="/reference/memory-types">
    Learn which memory type to pick for each piece of information.
  </Card>

  <Card title="Agent Management" icon="user-gear" href="/guides/agent-management">
    Create, activate, and switch Memanto agents.
  </Card>

  <Card title="Remember API" icon="floppy-disk" href="/api-reference/data/remember">
    The REST endpoint the `remember` MCP tool wraps.
  </Card>

  <Card title="Recall API" icon="magnifying-glass" href="/api-reference/search/recall">
    The REST endpoint the `recall` MCP tool wraps.
  </Card>
</CardGroup>

***

**Links**

* [`memanto-mcp` on PyPI](https://pypi.org/project/memanto-mcp/)
* [Memanto on GitHub](https://github.com/moorcheh-ai/memanto)
* [Model Context Protocol spec](https://modelcontextprotocol.io)
* [Anthropic MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)