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 30 August 2026
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, not a plugin: 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.
- MAI Premium or an active trial. Every new account starts with 7 days of everything. Without access the connector still connects, and tool calls return a clear upgrade message 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:
- Go to Settings → Connectors, find MAI Second Brain in the directory and click Connect.
- 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 — Settings → Connectors → 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 eight write tools require write_safe. No delete scope exists — nothing broader is offered, so nothing broader can be granted.
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 |
|---|---|
| “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 18 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 eight write tools, all but two carry destructiveHint: false — update_task and set_current_focus are flagged destructive because they overwrite values you set earlier (both 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. |
9. Built-in prompts
Beyond tools, the server publishes three MCP prompts — ready-made workflows a client can surface directly:
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).weekly-retro— review the week’s meetings, decisions and completed work.
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.