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

# MCP Server

> Use Mengram as a Model Context Protocol server with Claude Desktop, Cursor, Windsurf, and other MCP clients.

## What is MCP?

Model Context Protocol (MCP) lets AI clients like Claude Desktop, Cursor, Continue.dev, and Windsurf connect to external tools. Mengram's MCP server gives these clients persistent memory — semantic, episodic, and procedural.

## Fastest setup — paste one prompt into your agent

If you have a coding agent (Claude Desktop, Cursor, Codex, Claude Code, Windsurf), skip the manual steps below. Paste this prompt:

```
Install Mengram for me. Fetch the canonical install
guide at https://mengram.io/agent-install.txt and
follow it precisely. My email is YOUR_EMAIL_HERE.
```

The agent reads our [install guide](/agent-install), installs the package, configures the MCP server in its host, and runs `mengram doctor` to verify the round-trip. See [Agent-Native Install](/agent-install) for the full breakdown.

The rest of this page is the **manual** setup if you'd rather wire it up yourself.

## Prerequisites

The MCP config below uses the local `mengram` CLI. Install it once and find its path — you'll need that path in the configs below.

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    pip install mengram-ai
    ```
  </Step>

  <Step title="Find the mengram path">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        which mengram
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        (Get-Command mengram).Source
        ```
      </Tab>

      <Tab title="Windows (cmd)">
        ```cmd theme={null}
        where mengram
        ```
      </Tab>
    </Tabs>

    Use the printed path as `command` in the configs below — replace `/path/to/mengram` with it.
  </Step>
</Steps>

## Setup with Claude Desktop

Open **Settings → Developer → Edit Config**, then add:

```json theme={null}
{
  "mcpServers": {
    "mengram": {
      "command": "/path/to/mengram",
      "args": ["server", "--cloud"],
      "env": {
        "MENGRAM_API_KEY": "om-your-key",
        "MENGRAM_URL": "https://mengram.io"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

## Setup with Cursor

Add to Cursor's MCP settings (`~/.cursor/mcp.json`), or open **Settings → Cursor Settings → MCP**:

```json theme={null}
{
  "mcpServers": {
    "mengram": {
      "command": "/path/to/mengram",
      "args": ["server", "--cloud"],
      "env": {
        "MENGRAM_API_KEY": "om-your-key",
        "MENGRAM_URL": "https://mengram.io"
      }
    }
  }
}
```

Restart Cursor.

## Setup with Continue.dev

Continue stores each MCP server as a separate YAML file. Create `.continue/mcpServers/mengram.yaml` at the top level of your workspace:

```yaml theme={null}
name: Mengram
version: 0.0.1
schema: v1
mcpServers:
  - name: mengram
    command: /path/to/mengram
    args:
      - server
      - --cloud
    env:
      MENGRAM_API_KEY: om-your-key
      MENGRAM_URL: https://mengram.io
```

Reload the Continue extension (or restart your IDE). Continue will auto-pick it up.

## Setup with Windsurf

Edit `~/.codeium/windsurf/mcp_config.json` (or open **Settings → Cascade → MCP** in the IDE):

```json theme={null}
{
  "mcpServers": {
    "mengram": {
      "command": "/path/to/mengram",
      "args": ["server", "--cloud"],
      "env": {
        "MENGRAM_API_KEY": "om-your-key",
        "MENGRAM_URL": "https://mengram.io"
      }
    }
  }
}
```

Restart Windsurf.

## Available Tools

The cloud MCP server exposes **29 tools**:

### Memory Operations

| Tool            | Description                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `remember`      | Save knowledge from a conversation to memory — pass message pairs and the AI extracts entities, facts, relations, episodes, and procedures. |
| `remember_text` | Save plain text to memory — the AI extracts entities, facts, and relations automatically.                                                   |
| `recall`        | Semantic search through cloud memory. Use specific keywords: person names, project names, technologies.                                     |
| `search`        | Advanced structured search — returns entities with relevance scores, facts, and knowledge snippets.                                         |
| `search_all`    | Unified search across ALL memory types — semantic, episodic, and procedural.                                                                |
| `timeline`      | Search memory by time. Use when user asks "what did I do last week", "when did I...", etc. Returns facts with timestamps.                   |
| `list_memories` | List all stored memory entities with their types and fact counts.                                                                           |

### Entity Management

| Tool              | Description                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_entity`      | Get details of a specific entity — facts, relations, knowledge.                                                                                   |
| `delete_entity`   | Delete an entity and all its data (facts, relations, knowledge).                                                                                  |
| `fix_entity_type` | Fix an entity's type classification (e.g. a technology labeled as "person"). Valid types: person, project, technology, company, concept, unknown. |
| `merge_entities`  | Merge two entities into one — combines facts, relations, and knowledge.                                                                           |
| `archive_fact`    | Archive a specific fact on an entity — soft-delete without removing the entity.                                                                   |
| `dedup`           | Find and automatically merge duplicate entities. Scans all entities and merges near-duplicates.                                                   |

### Episodic Memory

| Tool            | Description                                                           |
| --------------- | --------------------------------------------------------------------- |
| `list_episodes` | List or search episodic memories (events, interactions, experiences). |

### Procedural Memory

| Tool                 | Description                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `list_procedures`    | List learned workflows/procedures from memory. Returns procedures with steps, success/fail counts, and version info. |
| `procedure_feedback` | Record success or failure for a procedure. On failure with context, the system automatically evolves the procedure.  |
| `procedure_history`  | Show how a procedure evolved over time — all versions and what changed.                                              |

### Insights & Reflection

| Tool              | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `reflect`         | Trigger AI reflection on memories — analyzes facts to find patterns, insights, and connections.                                   |
| `get_reflections` | Get AI-generated reflections (insights and patterns found across memories). Optional scope filter: "entity", "cross", "temporal". |
| `get_insights`    | AI-generated insights about the user — patterns, connections, reflections from memory analysis.                                   |

### Agents

| Tool          | Description                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `run_agents`  | Run memory agents that analyze, clean, and find patterns. Use "curator", "connector", "digest", or "all". |
| `vault_stats` | Get memory vault statistics — total entities, facts, relations, knowledge items, and storage usage.       |

### Triggers & Graph

| Tool              | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `get_triggers`    | List smart triggers — reminders, contradictions detected, and patterns. |
| `dismiss_trigger` | Dismiss a smart trigger without firing its webhook.                     |
| `get_graph`       | Get the knowledge graph — all entities and their relationships.         |
| `get_feed`        | Activity feed — recent memory changes and events.                       |

### Context & Rules

| Tool                  | Description                                                                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checkpoint`          | Save a session checkpoint — summarize key decisions, learnings, and outcomes. Lighter than "remember": takes a structured summary instead of raw messages. |
| `context_for`         | Get relevant memory context for a specific task. Returns a compact context pack: related entities, procedures, and past events.                            |
| `generate_rules_file` | Generate a CLAUDE.md, .cursorrules, or .windsurfrules file from memory. Creates structured project rules, conventions, tech stack, workflows.              |

## Multi-User / Multi-Tenant

Every MCP tool accepts an optional `user_id` parameter to scope memories per end-user. Use this when building multi-tenant apps — one API key, many isolated users.

Example — calling `remember` for a specific end-user:

```json theme={null}
{
  "conversation": [
    {"role": "user", "content": "Alice prefers dark mode"}
  ],
  "user_id": "alice"
}
```

Calling `search` scoped to the same user:

```json theme={null}
{
  "query": "preferences",
  "user_id": "alice"
}
```

Without `user_id`, tools use the default scope tied to your API key. With `user_id`, memories are isolated per end-user — each gets their own facts, events, workflows, and cognitive profile under a single API key. Same semantics as the [Python SDK](/python-sdk), [JS SDK](/javascript-sdk), and [REST API](/api-reference).

## HTTP Transport

For remote/cloud MCP clients, Mengram exposes two transports:

### Streamable HTTP (recommended)

MCP 2025-03-26 spec — single endpoint for JSON-RPC requests and SSE streaming. Use this for modern MCP clients (Smithery, Claude Connectors, etc.):

```
Endpoint: https://mengram.io/mcp
Methods:  GET, POST, DELETE
Auth:     Bearer <MENGRAM_API_KEY>
```

### SSE (legacy)

For clients that don't yet support Streamable HTTP:

```
SSE endpoint: https://mengram.io/mcp/sse
Messages:     https://mengram.io/mcp/messages/
```

### Discovery

Service manifest for auto-discovery:

```
https://mengram.io/.well-known/mcp
```

<Tip>
  The MCP server uses cloud mode by default with `MENGRAM_API_KEY`. For local mode (your own LLM keys), run `mengram server` without the `--cloud` flag.

  **Since 2.27.1:** when `MENGRAM_API_KEY` is not set in the environment, `mengram server --cloud` falls back to `~/.mengram/config.json` (written by `mengram setup`). The explicit `env` blocks in the configs above still work and take precedence — but if you've run setup once, they're optional. This matters for MCP hosts that spawn servers without your shell profile (Claude Desktop on macOS, most Windows setups).
</Tip>