MCP Server Overview¶

Mention exposes a Model Context Protocol (MCP) server so external agents — Claude, IDE-integrated assistants, custom internal tools — can use your organization's curated knowledge as a backend. An MCP client connects to the server, you sign in with your Mention account through a standard OAuth flow, and the client can then do what the Mention app does: list Audiences, work through Lessons one exercise at a time, run the review that falls due afterwards, read Articles, and ask grounded questions — and, for owners and admins, author tables of contents and track adoption. Everything is scoped to your own memberships and role.

This page covers what the MCP server is and how to connect to it. For the tool surface itself, see MCP Tools Reference.

What MCP is¶

The Model Context Protocol is an open protocol for connecting AI agents to external tools and data sources. An MCP server exposes a set of tools the agent can call and resources it can read; an MCP client (the agent) connects to the server, discovers the tools, and uses them as part of its reasoning.

Mention's MCP server is one such server. It lets agents bring the Articles your Audience owners commissioned into their context — and answer from them rather than from general knowledge — and it lets an agent teach the Lessons composed from those Articles, recording the same graded progress the Mention app records.

Why connect via MCP¶

The MCP server is the right surface when you want:

An external agent to answer questions grounded in your organization's source material without re-implementing retrieval or Article writing.
An agent to act as a tutor inside a tool your team already uses: it poses one exercise at a time, grades the attempt through Mention, and teaches from the verdict, working from the organization's own written answer.
A consistent, curated knowledge layer across multiple agents — internal chatbots, IDE assistants, voice agents — without copy-pasting your content into prompts.
An agent-first frontend to Mention itself: owners and admins can author tables of contents, resolve contradictions, and read adoption reports through the same connection.
Access that follows your own Audience memberships and role, so each person who connects sees exactly the knowledge domains — and exactly the capabilities — they have in Mention.

To make agents reach for Mention at the right moments, the connection is front-loaded: at session start the server sends the agent an inventory of your Audiences and their Article names, plus instructions to check Mention before performing or drafting any operational task from general knowledge. Saying "I need to issue an ops bulletin" to a connected agent matches the Issuing an Ops Bulletin Article by name and starts from the organization's own answer.

The MCP server is Mention's supported integration surface for agents; the underlying REST API is internal and changes without notice.

Authentication¶

The MCP server authenticates with OAuth 2.1 — the same standard modern MCP clients (Claude's connectors, Claude Cowork, IDE assistants) use. There is no API key to generate or paste.

When you add the server to a client, the client runs the OAuth flow for you:

The client discovers Mention's authorization server automatically from the server's metadata.
Your browser opens to sign in with your Mention account.
You pick which organization to connect on the consent screen.
The client receives an access token and stores it; it refreshes automatically.

The token represents you, so the server exposes exactly the Audiences you are a member of, the mode reported on each entry follows your own progress, and attempts submitted through the connection are attributed to you — they are the same progress records the Mention app shows. To change what an MCP connection can see, an admin changes your Audience memberships in the Mention app (see Managing Audiences) — there is nothing to configure on the connection itself.

How to connect¶

Configure your client with two things:

URL — https://mcp.mentionai.app/mcp
OAuth client ID — the pre-registered client ID for Mention's authorization server. Mention's sign-in provider grants the organization-selection scope only to pre-registered OAuth clients, not to dynamically registered ones — a client configured with the URL alone will sign in without the organization selector and cannot pick which organization to connect.

For example, in a Claude connector or Cowork, add a custom connector pointing at that URL with that client ID. The first time you use it, you will be prompted to sign in and choose your organization; after that the connection stays authorized until you disconnect it.

Once connected, the client discovers the available tools automatically. There is no separate handshake or session step, and no token to manage by hand.

What the server exposes¶

The tool list is role-scoped: every member gets the nine learner tools; Audience owners additionally get five curation tools; org admins get all sixteen.

Learner tools (everyone), in the order an agent would typically use them:

list_audiences — discover which Audiences you have access to.
read_audience — load one Audience's table of contents: every entry its owner commissioned, and whether each Article has been written yet. Documents and exercises are not included — drill in with the next tools.
read_article — load one Article's whole document. In Learn mode it also carries the lesson_id, so the agent can offer to teach the Lesson after answering what was asked.
read_lesson — in Learn mode, get the current exercise only: its setup, the options when it is a selection exercise, or whether it wants written prose — plus how far through the Lesson the user is. Answer keys, rubrics, and corrections are never included.
record_progress — submit an attempt at the current exercise and get the verdict back, with the correction to teach from and the next exercise.
roleplay — run the Audience's final exam once every Lesson is finished: check where the person stands, start the scene, relay each turn, and conclude to have the transcript graded.
review_session — draw and run the spaced-repetition review an Audience owes you: the material you already passed, back once it falls due, one item at a time.
read_concept — look up one term in the organization-wide vocabulary.
ask — ask a synthesized cross-cutting question for things no single Article covers. Requires audience_id and question; never call without both.

Owner tools (Audience owners and org admins): read_audience_admin, manage_members, manage_toc, read_adoption, manage_unanswered_questions.

Org admin tools: manage_audience, resolve_contradictions.

Alongside the tools, the server exposes one MCP resource per Audience — mention://audiences/{audienceId} — listable and readable by clients that surface resources, each a small JSON record with the Audience's id, name, and description.

Each tool is described in MCP Tools Reference, including when to prefer one over another.

Teaching over MCP¶

Conversation is a good surface for this, not a degraded one. Every kind of exercise Mention composes is something an agent can pose in a turn, free-response grading needs no renderer at all, and the final exam — a multi-turn roleplay against an agent that stays in character — is arguably better than the web version of the same thing.

The protocol the server instructs agents to follow is short:

Pose the exercise from read_lesson exactly as given — one at a time, without adding the answer.
Take the person's answer and submit it with record_progress.
Teach from what comes back: the verdict, the per-criterion feedback, the correction, and the reference answer. The graded verdict is the judgement, not the agent's own read of the answer.
Move to the next exercise, or offer the variant when they failed. A retry is the same material in a new situation, so the agent poses what comes back rather than repeating the question.

What makes this hold rather than being a polite request is that the agent does not have the answers — keys, rubrics, and corrections are stripped from everything a learner-scoped tool returns, and arrive only in the response to a submitted attempt, so an agent cannot reveal what it was never given. Reading the Article is no shortcut: the document states the material, it does not say which option the exercise wants.

record_progress writes your real Mention progress — the same records the web app shows — and requires you to be personally enrolled in the Audience. Org admins who are not enrolled get a permission error and should read without recording.

Review over MCP¶

Finishing a Lesson is not the end of the material: what you passed comes back on a schedule, and review_session is how a connected agent runs it. start draws whatever has fallen due in one Audience (or hands back a session you already have open), and each answer returns the verdict plus the next item inline, so the agent works through a session without reading it again between items.

Review keeps the same discipline as a Lesson — the agent poses one item, has none of the answers, and teaches from the graded verdict — with one difference worth knowing: there is no retry. A failed review item is still answered and the session moves on; the material drops to the shortest interval and comes back sooner instead. read tells you how many items starting would draw and, when that is none, when the next one returns — so the agent can point you at a session that exists, or say plainly that nothing is due rather than inventing practice questions of its own.

Composition latency¶

Articles are written when an owner adds an entry to an Audience's table of contents, and each Lesson is composed once its Article is finished, so both are normally ready long before anyone connects. If anything is still in flight, read_audience marks it inline, read_article returns _Still being written._ for that one entry, and read_lesson says the Lesson is still being composed — the client never blocks waiting for it.

Retry after ~30–90 seconds to pick up the fresh document. The same applies after an owner changes an entry's prompt, which makes Mention write the Article again and compose its Lesson again from the new document.