MCP servers

Companion is a client of MCP servers. Wire one in and the agent’s toolbox grows — Notion pages, Linear issues, GitHub repos, web search, your own tools.

Model Context Protocol is a standard JSON-RPC protocol for exposing tools to LLM agents. Companion connects to remote MCP servers and merges their tools into what the agent sees, each prefixed mcp_<slug>_<tool> to avoid name collisions.

Two transports: Streamable HTTP (the 2025 spec, preferred) and SSE (older fallback). A server exposes tools/list, tools/call, and optionally resources/* and prompts/list.

Add a server

Settings → Extensions → MCP servers → Add. Three pieces:

URL — the server’s HTTP endpoint.
Transport — streamable_http (preferred) or sse.
Auth — bearer (paste a token), oauth (full OAuth 2.1 + PKCE, including Dynamic Client Registration), or none.

Quick-add presets

Pick a preset and you only fill the differentiator (a token, or an OAuth sign-in):

Preset	Auth	What it brings
Notion	OAuth	Pages, databases, search.
Linear	OAuth	Issues, projects, comments.
GitHub	OAuth (via Copilot MCP)	Repos, issues, PRs (needs a Copilot sub).
Tavily	Bearer	Web search + extract.
Obsidian	Bearer	LAN bridge, vault read.
Filesystem	Bearer	LAN MCP fs server, local files.

Anything that speaks MCP works — for the rest, Custom → URL + auth.

The two auth flows

OAuth (Notion, Linear, GitHub) — click Sign in, approve on the provider’s consent screen, get redirected back; the row goes green. Tokens are stored encrypted and the access token rotates automatically. Disconnect drops both tokens locally (provider-side revocation is up to you). Dynamic Client Registration is handled transparently — you see the OAuth UI, you don’t manage client IDs.

Bearer (Tavily, custom) — paste URL + token, save. Companion does a tools/list round-trip and shows the tool count. The token is encrypted, scoped to your user.

When the tools actually fire

MCP tools are gated on the per-conversation Agent mode toggle (chat header):

Agent mode	Tools sent to the model
Off	none — a cheap, short prompt
On	workspace `fs_` + `rag_search` (if set) + web search (if Tavily on) + every enabled MCP server’s tools*

Skill tools are the exception — always on, regardless of agent mode, so the model can curate skills in any chat.

Housekeeping

Collisions — two servers each exposing search become mcp_notion_search and mcp_linear_search. The model sees prefixed names; you don’t manage them.
Tools cache — saved servers cache their tools/list for 5 minutes. Click Refresh on a row if the server changed its toolset.
Enable / disable — each row has a toggle; off skips the fetch and injects nothing, without removing the server.

MCP vs the rest

MCP servers — external tools the agent can call (this page).
Skills — task instructions the agent loads when relevant (Skills).
Agents tokens — the reverse: an external agent calling into Companion (Agents tokens).