Outline MCP Server: Complete Setup Guide (2026)

TL;DR + what you actually need

Outline is an open-source team wiki and knowledge base. An Outline MCP server lets an AI agent search, read, write, and organize the documents in your workspace without you copy-pasting context. The headline news for 2026: you almost certainly do not need to install anything.

• Official server (recommended default): built into every Outline workspace. Endpoint: https://<your-subdomain>.getoutline.com/mcp. Enable under Settings → AI. OAuth by default; API-key auth optional.
• Community server: vortiago/mcp-outline — a Python package you run with uvx mcp-outline. Uses an OUTLINE_API_KEY. Worth it for headless automation, granular access control, and self-hosted edge cases.
• Self-hosted Outline: both work. Swap the cloud subdomain for your own domain (/mcp for the official server, OUTLINE_API_URL for the community one).

The fastest official install, if you came here for the one-liner:

claude mcp add --transport http outline https://<yoursubdomain>.getoutline.com/mcp

Then type /mcp in Claude Code and finish the OAuth login in your browser. The rest of this guide explains the official-versus-community decision (the part most setup guides skip), walks the tools, and ends with the troubleshooting that bites people most often.

What the Outline MCP server actually does

The problem it solves is context switching. Your team’s runbooks, specs, onboarding docs, and meeting notes live in Outline. Your AI agent lives in Claude, Cursor, or a terminal. Without MCP, you paste doc text into a chat window by hand, the agent answers, and nothing it writes makes it back into the wiki. The Outline MCP server closes that loop: the agent queries Outline directly, grounds its answer in your real docs, and can write the result straight back as a new or edited document.

Outline describes it plainly in its own changelog: MCP lets AI assistants “directly search, read, create, and edit documents in your Outline workspace” so they become “an extension of your knowledge-base.” That framing matters because it’s a two-way integration — read and write — not a read-only search box. An agent can find the stale deployment doc, update it with the new steps, and leave a comment explaining why.

Both the official and community servers talk to the same Outline API. The difference is in how they authenticate, where they run, and how much control they hand you. That’s the next section, and it’s the decision that actually matters.

You can browse the community server’s catalog entry, badges, and live config on its Outline server page — that’s the canonical reference for its install snippets, which stay in sync with this post.

Official vs community: the honest comparison

Outline shipped its official MCP server on February 18, 2026. The announcement is blunt about the goal:

For most people that ends the conversation. The official server is hosted by Outline, needs no local install, and authenticates with OAuth — you paste the URL into your client and a login window appears. Two community servers predate it: mmmeff/outline-mcp-server (now explicitly deprecated, its README points everyone at the official server) and Vortiago/mcp-outline, which is still maintained and still recommends the official server in its own README.

So why would you reach for the community server? One word that the OAuth-by-default design surfaces: expiry. OAuth access tokens issued by the official server are short-lived, and that became a real friction point. A user raised it directly with the maintainers:

Outline’s founder agreed and shipped API-key auth shortly after — so the official server now accepts an Authorization: Bearer <key> header too. That closes most of the gap. What remains is control: the community server exposes knobs the hosted one doesn’t — read-only mode, disable-delete, per-user API keys in HTTP mode, dynamic per-role tool filtering, batch operations, and tunable connection pools and cache TTLs. If you’re wiring Outline into an unattended pipeline or want to hand an agent a deliberately narrow set of permissions, those knobs are the reason to run it yourself.

Our take, before the details: start with the official server; reach for vortiago/mcp-outline when OAuth’s hourly login or its all-or-nothing permissions get in your way.

Install (official + community)

Official server (cloud)

First, enable MCP for the workspace: an admin opens Settings → AI and toggles MCP on. (If connections fail with no error, this toggle being off is the usual reason.) Then connect your client to https://<yoursubdomain>.getoutline.com/mcp. Outline only supports the Streamable HTTP transport, so older stdio-only clients need a proxy (covered below).

Claude Code:

claude mcp add --transport http outline https://<yoursubdomain>.getoutline.com/mcp

Then run /mcp inside Claude Code to trigger the OAuth flow. For Claude Code and other clients, the install paths are catalogued at mcp.directory/clients.

Cursor: open Cursor Settings → MCP → Add new global MCP server and paste:

{
  "mcpServers": {
    "outline": {
      "url": "https://<yoursubdomain>.getoutline.com/mcp"
    }
  }
}

Claude Desktop: open Settings → Connectors → Add Connector and enter the same /mcp URL.

stdio-only clients: if your app only speaks local stdio, bridge to the remote endpoint with the mcp-remote proxy:

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<yoursubdomain>.getoutline.com/mcp"]
    }
  }
}

For API-key auth instead of OAuth, generate a key in Outline (Settings → API Keys) and add it to your client’s MCP header config as Authorization: Bearer <your-api-key>. Prefer this for anything headless.

Community server (vortiago/mcp-outline)

The community server runs locally as a Python process. Get an API key first (Settings → API Keys → New API Key), then the one-line Claude Code install:

claude mcp add mcp-outline uvx mcp-outline

Set OUTLINE_API_KEY in your shell profile (~/.zshrc or ~/.bashrc) before you start the client; if it’s missing, every tool call returns an error with setup instructions. The manual JSON form, which works in Claude Desktop, Cursor, VS Code, Cline, and most other clients:

{
  "mcpServers": {
    "mcp-outline": {
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "<YOUR_API_KEY>",
        "OUTLINE_API_URL": "<optional, for self-hosted>"
      }
    }
  }
}

Prefer not to use uvx? The package also installs via pip install mcp-outline, and a Docker image at ghcr.io/vortiago/mcp-outline runs it in HTTP mode for remote access. The install panel below pulls the community server’s configs straight from our catalog, so it stays current as the package ships new client integrations.

One-line install · Outline

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Self-hosted Outline

Running your own Outline instance changes one thing: the URL. For the official server, replace the cloud subdomain with your installation domain and append /mcp — for example https://wiki.yourcompany.com/mcp. For the community server, set the API base explicitly:

{
  "mcpServers": {
    "mcp-outline": {
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "<YOUR_API_KEY>",
        "OUTLINE_API_URL": "https://your-domain/api"
      }
    }
  }
}

Two self-hosted footguns worth flagging now. If your instance uses a self-signed TLS certificate, set OUTLINE_VERIFY_SSL=false on the community server (and only then). And if your self-hosted Outline has no OpenAI integration configured, the AI tools will fail — set OUTLINE_DISABLE_AI_TOOLS=true so the agent doesn’t try to call them.

The tools, walked through

The community vortiago/mcp-outline server exposes the larger, more granular tool set, so it’s the clearest one to walk. The official server covers the same core operations through the same API; tool naming differs but the capabilities overlap.

Two tools are worth calling out because they change how the agent behaves. edit_document takes batched string-match replacements and a save flag: with save=False it stages edits locally, and only the final call with save=True pushes everything to Outline. That lets an agent assemble a multi-part edit and commit it once, instead of hammering the API per change. And read_document_section means the agent can pull just the “Rollback” heading out of a 2,000-line runbook rather than the entire document — a real token saver on big wikis.

There’s also ask_ai_about_documents, which routes a natural-language question through Outline’s own AI over your docs, and a full set of batch_* tools for creating, updating, moving, archiving, or deleting many documents in one call. The opinionated takeaway: the batch and staged-edit design is what makes this server usable for bulk wiki reorganization, not just one-doc Q&A.

MCP Resources via outline:// URIs

Beyond tools, the community server exposes MCP Resources — addressable content the client can read directly by URI, without a tool call. The scheme is outline://:

outline://document/{id}             # full document markdown
outline://document/{id}/backlinks   # docs that link to this one
outline://collection/{id}           # collection metadata
outline://collection/{id}/tree      # hierarchical document tree
outline://collection/{id}/documents # flat list of documents

Resources matter when a client supports attaching them as context. Instead of asking the agent to “search for the onboarding doc and read it,” you hand it outline://document/abc123 and the content is already in scope. The backlinks resource is the quiet standout: it surfaces every document that references the one you’re looking at, which is how you trace the blast radius before editing a widely-linked page.

Recipes

Five workflows where an Outline MCP server earns its keep. These assume the server is installed and connected in your client of choice.

Recipe 1 — Answer from the wiki, not from training data

Ask: “What’s our incident escalation process? Check Outline.” The agent runs search_documents, reads the matching runbook, and answers grounded in your actual process — not a plausible-sounding guess. The whole point of a knowledge-base MCP is replacing the model’s imagination with your documents.

Recipe 2 — Draft a doc and file it correctly

After a design review: “Write up these decisions as a doc in the Architecture collection.” The agent calls list_collections to find the right collection ID, then create_document with the content. The doc lands where your team expects it, not in a random location.

Recipe 3 — Keep a runbook current

You changed the deploy steps: “Update the deployment runbook — the migration step now runs before the build.” The agent finds the doc, uses read_document_section to pull just the deploy steps, and edit_document to splice in the change. Stale runbooks are how outages happen; this shortens the gap between “process changed” and “doc reflects it.”

Recipe 4 — Reorganize a messy collection

A collection has grown into a swamp. “Archive every doc in Scratch that hasn’t been touched this year.” The agent lists the collection, identifies stale docs, and uses batch_archive_documents to clear them in one call instead of dozens. Read-only or disable-delete mode is your seatbelt here — see the access-control section.

Recipe 5 — Trace before you edit

Before changing a foundational doc: “What links to our API authentication doc?” The agent reads outline://document/{id}/backlinks (or calls get_document_backlinks) and lists every dependent page, so you know what you’ll break before you touch it.

What we got wrong setting this up

Two things bit us, both avoidable in hindsight.

We pointed an automation at the OAuth endpoint. The official server’s OAuth flow is great for interactive use in Claude or Cursor. We wired it into a scheduled job and the job died roughly every hour when the access token expired and there was no browser to refresh it. The fix was the API-key path — Authorization: Bearer <key> — or switching that particular workload to the community server, which is built around a static key. The 60-minute expiry is not a bug; it’s just the wrong auth mode for headless work.

We left the AI tools enabled on a self-hosted instance with no OpenAI key. The community server’s ask_ai_about_documents needs Outline to have an AI provider configured. On our self-hosted box that wasn’t set up, so those calls failed confusingly until we set OUTLINE_DISABLE_AI_TOOLS=true. If you’re self-hosting without Outline’s AI features, disable the AI tools up front.

Access control & safety

An MCP server that can delete documents is an MCP server that can delete the wrong documents. The community server takes this seriously and gives you env-var guardrails — this is one of its clearest advantages over the hosted default.

Read-only mode takes precedence over disable-delete. The safe default for any agent that only needs to answer from the wiki is OUTLINE_READ_ONLY=true — turn writes on deliberately, per workflow, rather than leaving a fully-armed editor connected by default. For multi-user HTTP deployments, the x-outline-api-key header means each person’s agent acts with their own Outline permissions, instead of one shared service key that sees everything.

Troubleshooting

The Verdict

If you’re still deciding which knowledge base to wire your agent into, our roundup of the best knowledge base MCP servers compares Outline against Notion and Confluence. And if your notes live in a single-user vault rather than a team wiki, the Obsidian MCP guide covers that path.

Frequently Asked Questions

Glossary

• Outline — open-source team wiki and knowledge base; available cloud-hosted at getoutline.com or self-hosted.
• MCP (Model Context Protocol) — open standard that lets AI clients call external tools and read external resources over a defined wire format.
• Official Outline MCP server — the MCP endpoint built into every Outline workspace; Streamable HTTP, OAuth or API-key auth.
• vortiago/mcp-outline — the community Python MCP server for Outline; API-key auth, run via uvx mcp-outline.
• OAuth — browser-based auth flow; convenient interactively, but its access tokens expire (~60 min here).
• Streamable HTTP — the HTTP-based MCP transport the official Outline server requires; stdio clients need a proxy.
• MCP Resource — addressable content a client reads by URI (here, outline://) without a tool call.
• stage-then-save — the community server’s edit pattern: queue edits with save=False, commit once with save=True.
• Read-only mode — OUTLINE_READ_ONLY=true; disables every write so the agent can only search, read, and export.

Sources

• Official Outline MCP docs: docs.getoutline.com — MCP guide (client setup, OAuth + API-key auth, Settings → AI)
• Outline MCP launch changelog: getoutline.com/changelog/mcp (Feb 18, 2026 — “built-in” framing)
• Community server repo & README: github.com/Vortiago/mcp-outline (MIT, Python; tools, resources, access control)
• Community server client-setup docs: docs/client-setup.md
• Deprecated server (points to official): github.com/mmmeff/outline-mcp-server
• API-key auth discussion + maintainer response: outline/outline Discussion #11797
• npm/PyPI package: pypi.org/project/mcp-outline
• Catalog entry: mcp.directory/servers/outline