---
title: MCP server
description: Connect Memoria to Claude Code and other MCP clients. Twelve tools, OAuth 2.1 authentication, one install line.
order: 2
---

# MCP server

Memoria exposes its memory operations as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server. Any MCP-aware client — Claude Code, Claude Desktop, Cursor, your own agent — can connect and use Memoria's twelve tools without writing API glue.

The server lives at `https://api.memoria.premex.se/mcp` and speaks streamable HTTP.

## Connect from Claude Code (recommended)

Memoria supports OAuth 2.1, so you don't need to paste API keys into config files. From any project:

```bash
claude mcp add memoria https://api.memoria.premex.se/mcp
```

When you first use a Memoria tool, Claude Code opens a browser tab. Sign in with your Memoria account, pick the brain you want this session bound to, click Authorize. Done — the access token is stored by Claude Code, refreshed automatically, and never touches your repo.

## Connect with an API key (alternative)

For long-running agents or CI environments where browser flow isn't an option, use a `mem_live_*` API key directly:

```json
{
  "mcpServers": {
    "memoria": {
      "url": "https://api.memoria.premex.se/mcp",
      "headers": {
        "Authorization": "Bearer mem_live_…"
      }
    }
  }
}
```

The API key already binds to a single brain (created when you generated the key in the dashboard), so no brain picker shows up.

> **Want the setup in one line — including the agent-teaching skill?** The [memoria CLI](/docs/cli) installs the binary, wires this MCP entry, and keeps your key out of the config file. It's the recommended path for Claude Code on the web and other cloud environments — see the [CLI](/docs/cli) guide.

## The twelve tools

### Generic tools

| Tool | What it does |
|------|--------------|
| `remember` | Store a new memory. Triggers the full 7-stage extraction pipeline. |
| `recall` | Hybrid retrieval — dense + sparse + graph, fused and re-ranked. |
| `forget` | Mark an edge as no-longer-valid (bi-temporal soft delete). |
| `relate` | Manually create or update a relationship between two entities. |
| `recall_history` | Inspect how a fact has changed over time. |
| `get_playbook` | Fetch a stored playbook by slug. |

### Coding pack

These wrap the generic tools with automatic metadata, optimised for coding agents.

| Tool | What it does |
|------|--------------|
| `record_decision` | Capture an architectural decision with rationale. |
| `record_convention` | Note a project-specific coding convention. |
| `record_gotcha` | Stash a gotcha that bit you so it won't bite again. |
| `record_session_outcome` | End-of-session summary — what shipped, what's pending. |
| `recall_repo_context` | Pre-flight recall for a repo: decisions, conventions, gotchas. |
| `regenerate_playbook` | Rebuild a generated playbook from current memories. |

## Authentication details (for advanced users)

The MCP server implements:

- [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) — OAuth 2.0 Protected Resource Metadata
- [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) — OAuth 2.0 Authorization Server Metadata
- [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) — PKCE (S256, mandatory)
- [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) — Dynamic Client Registration

Discovery endpoints:

```
GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-authorization-server
```

Public clients only (`token_endpoint_auth_methods_supported: ["none"]`). Refresh tokens rotate on every use; the old token is invalidated.

## Troubleshooting

- **"Protected resource URL doesn't match"** — your client is comparing against `http://`. Check that `/.well-known/oauth-protected-resource` returns `https://`.
- **Tool calls return 401 with `invalid_token`** — your access token expired. Refresh tokens last 30 days; access tokens last 1 hour and refresh automatically.
- **"No brain selected"** on the consent screen — pick a brain before clicking Authorize. If you have only one brain, it's pre-selected; with multiple brains the first is pre-selected.

See [Brains](/docs/brains) for how brain selection bonds to API keys and OAuth tokens.