MCP Setup Guide

Connect your AI assistant to your Retain data

Retain uses the Model Context Protocol (MCP) to let AI assistants read and manage your todos, categories, and projects. One API key works with any MCP-compatible client.

Step 1: Generate an API key in the Retain app (Settings → API).
Step 2: Pick your client below and add the config.

Claude Code (CLI)

Anthropic's CLI agent for software engineering.

Step 1 — Open your MCP config

Open or create ~/.claude/.mcp.json for global access, or .mcp.json in any project root for project-scoped access.

Step 2 — Add the Retain server

Paste this into the file. Merge with existing entries if you already have other MCP servers.

{ "retain": { "type": "streamable-http", "url": "https://mcp.retainapp.dev/mcp", "headers": { "Authorization": "Bearer your-key-here" } } }

Step 3 — Verify

In Claude Code, run /mcp — Retain should appear with a green status indicator.

Tip: Ask Claude to "list my todos" or "add a todo to buy groceries" to test the connection.

Claude Desktop

Anthropic's desktop app for macOS and Windows.

Step 1 — Open config

Open Claude Desktop → Settings (gear icon) → Developer → Edit Config.

Step 2 — Add to mcpServers

Add this inside the "mcpServers" object in the config file:

"retain": { "type": "streamable-http", "url": "https://mcp.retainapp.dev/mcp", "headers": { "Authorization": "Bearer your-key-here" } }

Step 3 — Restart

Quit and reopen Claude Desktop. Retain should appear under your MCP servers list.

Cursor

AI-native code editor built on VS Code.

Step 1 — Open MCP config

Create .cursor/mcp.json in your project root. Or open Cursor Settings → MCP.

Step 2 — Add Retain

{ "mcpServers": { "retain": { "url": "https://mcp.retainapp.dev/mcp", "headers": { "Authorization": "Bearer your-key-here" } } } }

Step 3 — Verify

Open Cursor's MCP panel — Retain should show a green dot. In Composer, ask the agent to read your todos.

VS Code (GitHub Copilot)

GitHub Copilot's agent mode with MCP support.

Step 1 — Open MCP config

Create .vscode/mcp.json in your project root.

Step 2 — Add Retain

{ "servers": { "retain": { "type": "http", "url": "https://mcp.retainapp.dev/mcp", "headers": { "Authorization": "Bearer your-key-here" } } } }

Step 3 — Verify

In Copilot Chat (agent mode), type @retain — it should autocomplete if connected. Ask it to list your todos.

Note: MCP in Copilot requires VS Code 1.99+ and Copilot Chat in agent mode. Make sure "chat.agent.enabled": true is in your settings.

Windsurf

Codeium's AI-powered IDE.

Step 1 — Open MCP config

Open ~/.codeium/windsurf/mcp_config.json, or go to Windsurf Settings → MCP.

Step 2 — Add Retain

{ "mcpServers": { "retain": { "serverUrl": "https://mcp.retainapp.dev/mcp", "headers": { "Authorization": "Bearer your-key-here" } } } }

Step 3 — Verify

Open Windsurf's MCP panel to confirm the connection. Ask Cascade to interact with your todos.

Note: Windsurf uses serverUrl instead of url in its config format.

Cline

Autonomous AI coding agent for VS Code.

Step 1 — Open MCP settings

Open the Cline sidebar → MCP Servers → Configure MCP Servers.

Step 2 — Add Retain

{ "mcpServers": { "retain": { "url": "https://mcp.retainapp.dev/mcp", "headers": { "Authorization": "Bearer your-key-here" } } } }

Step 3 — Verify

Retain should appear in Cline's MCP Servers list with a green indicator. Ask Cline to list your todos to test.

OAuth (no API key)

claude.ai (Web)

Claude on the web connects via OAuth — no API key needed.

Step 1

Go to claude.ai → Settings → Integrations.

Step 2

Click "Add custom connector".

Step 3

Name: Retain · URL: https://mcp.retainapp.dev/mcp

Step 4

Leave advanced settings empty → click Add → click Connect.

Step 5

Tip: Once connected, you can ask Claude to "show my todos" or "add milk to my grocery list" in any conversation.

Troubleshooting

Connection not showing up?

Make sure your AI client is fully restarted after editing the config. Some clients require a full quit-and-reopen, not just a window refresh.

Authentication errors?

Double-check that your API key is copied correctly with no extra spaces. Keys look like: camp-would-anthem-aged. If your key was rotated, you'll need the new one from the app.

Rate limit warnings?

Free accounts have 30 MCP write operations per day (adds, updates, completes, deletes). Reads never count — listing todos, projects, categories, tags, and usage is always free and unlimited. Upgrade to Pro for unlimited operations.

Need help?

Email [email protected] — it goes to a real person.