MCP server documentation
Everything the MAI connector does, documented end to end — how to connect, how authentication works, every tool it exposes, its limits, and how it treats your data. For the short version, see the connector overview.
Last updated 29 September 2026
Start here: four starter skills
The quickest way to see what MAI does is to let the AI you already use fill your brain for you. Once MAI is connected, say one of these:
| Say | What happens |
|---|---|
“Map my brain”map-my-brain | Turns what your assistant already knows about you into projects, a brief note for each, an “About me” note and your Current Focus. It shows the plan, reuses what’s already in your brain, and asks before writing anything. |
“Save this to my brain”save-to-brain | Saves the current chat as one structured note in the right project, and its action items as tasks if you want them. |
“Daily brief”daily-brief | Researches the topics you follow on the web, relates them to your work, and saves the brief as a note you can read or play with Listen. Where your app supports scheduled tasks, it offers to run every morning. |
“Weekly review”weekly-review | Saves the week’s wins, slips and themes as a note, clears stale tasks with you, and agrees next week’s focus. |
Start with “map my brain”, then open Brain in the MAI app to see your projects laid out as a map. From then on, new voice notes are filed into those projects automatically.
Add the plugin
The four skills ship as the MAI Second Brain plugin in Anthropic’s directory, and the plugin brings the MAI connector with it.
- claude.ai, the Claude apps and Cowork: open Customize → Plugins, search Discover for MAI Second Brain and click Add. Then open the plugin’s Connectors tab and connect MAI with your account. Type
/to pick a skill, or just say the phrase. Directory plugins appear on Pro and Max plans, and on Team and Enterprise plans whose owner includes the directory. - Claude Code: a plugin you add on claude.ai arrives in Claude Code on its own the next time you start it signed in to the same account (Claude Code 2.1.273 or later). Or install it from the command line: run
/plugin marketplace add iseko007/mai-second-brain-plugin, then/plugin install mai-second-brain@mai-second-brain, and sign in from/mcp. The source is on GitHub. - Only the skills: download map-my-brain, save-to-brain, daily-brief, weekly-review and upload each ZIP under Customize → Skills, with MAI connected under Customize → Connectors.
- Claude Code, connector only: the same flows are built into the connector as prompts:
/mcp__mai__map-my-brain,/mcp__mai__save-to-brain,/mcp__mai__daily-briefand/mcp__mai__weekly-retro(named for whatever you called the connector). - ChatGPT: the skills arrive with the next version of the MAI plugin for ChatGPT.
1. Overview
MAI is an agent-first second brain you fill by voice — notes, meetings, tasks and projects, captured on iPhone, Apple Watch and Mac and structured from the start for an AI to read, not just a human. Its MCP server is the front door: it lets any AI assistant that speaks the Model Context Protocol read that brain and write back into it: search your entries, pull a meeting transcript, check today’s Focus Brief, create tasks and save notes.
The server is remote — there is nothing to install:
https://maicontext.com/mcpTransport is streamable HTTP (a single stateless endpoint; SSE-only clients are not required), protocol revision 2025-11-25. Every user connects to the same URL, and every request runs as the account that approved the connection — one person’s brain, never anyone else’s.
Connections made at the legacy address mcp.somaflow.app keep working indefinitely; new connections should use the URL above.
2. Requirements
- An MAI account, and the app to capture content with — the connector is the bridge, not the brain. Get the app free on the App Store.
- An active MAI plan. Without one the connector still connects, and tool calls return a clear message saying so rather than an error.
- An MCP client that supports remote servers — claude.ai, Claude Desktop, Claude Code, ChatGPT (Developer mode), Lovable, MCP Inspector, or your own scripts.
3. Connect Claude (claude.ai & Desktop)
MAI is listed in Claude’s connector directory, so the fastest path involves no URL at all:
- Open Customize → Connectors, search for MAI Second Brain and click Connect. If you added the MAI Second Brain plugin, this is the connector on its Connectors tab: connecting either one covers both.
- A browser window opens MAI’s sign-in page — enter your account email, type the 6-digit code it sends you, and approve. That sign-in is the authorization.
- The connector appears with a Connected badge. Enable it in a chat from the + / connectors menu.
Adding it manually also works — Customize → Connectors → Add → Add custom connector with https://maicontext.com/mcp — and is the route for MCP clients without a directory.
On the Claude mobile apps, connect once on claude.ai in a browser and the connector syncs to your phone.
4. Connect Claude Code
One line in your terminal, then approve the sign-in it opens:
claude mcp add --transport http mai https://maicontext.com/mcpClaude Code runs the same browser OAuth flow as claude.ai. If you’d rather use a personal access token (for headless machines or scripts), generate one in the app — see Authentication & tokens — and add it as an Authorization: Bearer header instead.
5. ChatGPT & other MCP clients
ChatGPT supports custom connectors behind Developer mode on paid plans: turn on Settings → Apps → Advanced settings → Developer mode (on a company workspace an admin must allow custom connectors first), then Settings → Connectors → Create, name it MAI, paste the same URL and sign in when it asks.
Codex (OpenAI’s coding agent) connects from its config: add a server named mai to ~/.codex/config.toml with url = "https://maicontext.com/mcp", then run codex mcp login mai and approve the browser sign-in. A personal access token in an Authorization: Bearer header works there too.
Anything else that speaks MCP — Lovable, MCP Inspector, an agent framework, your own code — connects with the same URL. Clients that support OAuth get the browser sign-in; clients that don’t can send a personal access token as a bearer header.
6. Authentication & tokens
OAuth (Claude, ChatGPT and other OAuth-capable clients)
The server implements OAuth 2.1: authorization code with PKCE (S256, required), dynamic client registration (RFC 7591), single-use authorization codes, refresh-token rotation, and standard discovery documents (RFC 8414 and RFC 9728). Signing in happens on our own page: MAI accounts authenticate with a one-time emailed code, or with a password for accounts that have set one — the client never sees either, only the resulting authorization. Access tokens last 30 days and refresh automatically.
Note that claude.ai does not accept pasted bearer tokens — OAuth is the path there.
Personal access tokens (CLI and scripts)
Generate one in the app: on Mac under Settings → Claude Connectors, on iPhone under Profile → Connect to Claude. Tokens are shown exactly once and stored only as a SHA-256 hash; they don’t expire until you revoke them.
Scopes
Two scopes exist: read and write_safe (both granted by default). Read tools require read; the ten write tools require write_safe. No delete scope exists — nothing broader is offered, so nothing broader can be granted.
Project-scoped tokens
A personal access token can be limited to one or more of your projects, for an automation that should see one corner of your brain and nothing else — a support agent reading only your Support project, say. Create it on Mac under Settings → Claude Connectors: pick the projects under Access before you generate the token. The token list marks each one with the projects it can reach. Tokens issued through the OAuth sign-in always cover the whole brain.
A project-scoped token can call six tools, and only these:
search_entries,list_recent_entries,get_entryandlist_projects— they return only notes and projects inside the scopecreate_text_entryandappend_to_entry— new notes are filed in the scope, and only notes already in it can be appended to
Every brain-wide tool — tasks, meetings, themes, your Focus Brief and Current Focus, creating or editing projects — is hidden from tools/list and refused if called anyway. With a single project, project_id is pinned automatically: the client never has to pass it, and any other value is refused. With several projects, the search, list and create tools need a project_id from that set. A note outside the scope reads as not found. If every project in the scope is deleted, the token can no longer do anything; create a new one. The read and write_safe scopes still apply on top.
Revoking access
The same screens list every active connection — OAuth ones appear as “Claude (OAuth)” — and one click revokes. Revocation is immediate; an OAuth client simply re-runs the sign-in flow the next time you use it.
7. Example prompts
Once connected, you just talk — the assistant picks the tools. Prompts that exercise different parts of the surface:
| Try asking | Tools exercised |
|---|---|
| “Map my brain from what you know about me.” | list_projects · create_project · create_text_entry · set_current_focus |
| “Brief me every morning on AI in dental clinics.” | create_project · create_text_entry |
| “What did I decide about pricing in the last two weeks?” | search_entries |
| “Summarize yesterday's product meeting and pull out what I promised to do.” | list_meetings · get_meeting_transcript |
| “What should I focus on today?” | get_focus_brief · list_tasks |
| “Remind me to follow up with Sarah on Friday.” | create_task |
| “Save what we just worked out as a note in my brain.” | create_text_entry |
| “Add that decision to my pricing note.” | search_entries · append_to_entry |
| “Extract the action items from my last voice note.” | list_recent_entries · generate_actions_for_entry |
8. Tool reference
The server exposes 20 tools, each published with a human-readable title and the MCP annotations clients use for permission UX. The ten read tools carry readOnlyHint: true and destructiveHint: false. Of the ten write tools, all but three carry destructiveHint: false — update_task, set_current_focus and update_project are flagged destructive because they overwrite values you set earlier (all three return the previous values so a mistake can be undone). Every tool carries openWorldHint: false: nothing here reaches outside your own brain. No delete tool exists.
Read tools
| Tool | Title | What it does |
|---|---|---|
search_entries | Search Second Brain | Hybrid keyword + semantic search across every note, meeting and task. Optional project and source-type filters. |
list_recent_entries | List Recent Entries | Newest-first entries, optionally limited to the last N days, one project, or one source type. |
get_entry | Get Entry | One entry in full — summary, content, tasks. Long content paginates via max_chars and offset. |
list_meetings | List Meetings | Recent meetings with platform, duration and participants. |
get_meeting_transcript | Get Meeting Transcript | The speaker-attributed transcript and decisions of one meeting, paginated. |
list_tasks | List Tasks | Tasks filtered by completion, project, parent entry or scheduled date. |
get_user_themes | Get Themes & Working Style | The recurring themes and working style MAI has learned from your capture history. |
get_focus_brief | Get Focus Brief | The latest daily or weekly Focus Brief — your synthesized priorities. |
get_current_focus | Get Current Focus | Your confirmed ventures and goals. |
list_projects | List Projects | Your projects and the folders inside them. |
Write tools
| Tool | Title | What it does |
|---|---|---|
create_task | Create Task | A new task — standalone on the daily Actions list, or attached to an entry. Supports due date, priority and project. |
toggle_task | Complete / Reopen Task | Marks a task done or reopens it. The only tool that touches completion. |
update_task | Update Task | Edits a task's title, description, priority, due date or project — never its completion state. |
create_text_entry | Save Note to Second Brain | A new structured text note. The server enforces the app's note shape, so saved notes read like your own. |
append_to_entry | Append to Note | Adds a section to an existing text note. Voice and meeting entries are immutable — what you said stays as you said it. |
assign_entry_to_project | Assign Entry to Project | Links an entry to a project, or unlinks it. |
set_current_focus | Set Current Focus | Replaces your ventures and goals, returning the previous values so nothing is silently lost. |
generate_actions_for_entry | Generate Actions for Entry | Extracts tasks from one entry — only when you explicitly ask; it never runs on its own. |
create_project | Create Project | A new project with emoji, description, goal and keywords, the details MAI uses to file new notes. Returns the existing project instead of a duplicate when the name is taken. |
update_project | Update Project | Edits a project's name, emoji, description, goal, keywords, colour or deadline, returning the previous values. |
9. Built-in prompts
Beyond tools, the server publishes six MCP prompts, ready-made workflows a client can surface directly:
map-my-brain— build your brain from what your assistant already knows about you.save-to-brain— save the current chat as a structured note, with its tasks.daily-brief— research your topics on the web and save the brief as a note (optionaltopicsargument).weekly-retro— the weekly review: wins, slips and themes saved as a note, stale tasks cleared with you, next week’s focus agreed.daily-review— walk through today’s brief, open tasks and recent captures.meeting-prep— gather everything you know about a company, person or topic before a call (takes atopicargument).
Claude Code surfaces them as slash commands (/mcp__mai__daily-review and friends, named for whatever you called the connector). Clients without a prompt picker reach the same value by just asking — the tools carry the workflow.
10. Rate limits
Three tools call AI models on our side and carry per-account hourly caps; everything else is a plain database operation and is uncapped:
| Tool | Cap |
|---|---|
search_entries | 120 calls per hour |
create_text_entry | 60 calls per hour |
generate_actions_for_entry | 60 calls per hour |
The caps are far above conversational use — they exist to stop runaway automation, not you. Hitting one returns a clear message in the tool result; wait a bit and retry.
11. Data handling & security
- Scoped to you. Every request is authenticated and filtered to your account server-side. The connector can only ever see the brain of the person who approved it.
- Additive writes. The connector can create and update; deleting is reserved for you, in the app. Voice and meeting entries can’t be modified at all.
- Audited. Every tool call is logged, and the log is retained for 90 days.
- Stored in the EU. Your content lives on infrastructure in the European Union, encrypted in transit and at rest.
- Your assistant, your agreement. The AI you connect receives whatever the connector returns to it. What that assistant’s provider does with it is governed by your agreement with them — connect assistants you trust.
The full picture — every processor, retention periods, your rights — is in the privacy policy.
12. Troubleshooting
- New tools don’t show up. claude.ai caches the tool list aggressively. Disconnect the connector and add it again; Claude Code picks changes up on restart.
- Can’t add the connector on your phone. Custom connectors are added on claude.ai in a browser; the connection then syncs to the mobile apps.
- “Premium required” in tool results. Your trial ended or the subscription lapsed. Upgrade in the MAI app; the connector works again immediately — no reconnect needed.
- 401 or a failed connection. The token was revoked or the OAuth grant expired. Reconnect (or generate a fresh token) and it’s resolved.
- Connected at mcp.somaflow.app? That address keeps working — no need to re-add anything.
13. Support
Stuck, or found something this page doesn’t answer? Write to ivo@maicontext.com — a human reads it.
See also the Privacy Policy and Terms of Service.