Connect the Outline Wiki built-in MCP service to Claude Code'sone-time configuration skill.
This skill solves the "not visible in the tool list mcp__outline__*" type ofconfiguration-phaseissue—
the specific document operations of search / read / write / edit are handled by outline-wiki-search SKILL.md
and outline-wiki-upload SKILL.md respectively.
After completing this skill's work, the configuration information is written to disk according to the selected scope (project default → repository root
.mcp.json;user / local → ~/.claude.json), and the agent can call
outline MCP tools within the current project; after that, all outline document operations are taken over by the other two skills.
When to use / not use
Use
- The user first mentions "connecting outline / configuring outline MCP / how to connect outline"
- The user's endpoint form is
https://<your-subdomain>.getoutline.com/mcporhttps://<your-domain>/mcp(self-hosted) - The current session calling the
mcp__outline__*tool fails, with a message that it is not registered / connection refused - The user already has API Key(Settings → API) or goes through OAuth browser login
- Need to troubleshoot configuration-phase issues such as "configuration write failed / after restart /mcp cannot see outline / 401 / 403"
- The client is Claude Code / Claude Desktop / Cursor / another MCP client that supports Streamable HTTP transport
Do not use
- Search / read outline documents—go to
outline-wiki-searchSKILL.md - Write / edit outline documents(including image attachments / @mention / comments / Collection management
/ move / delete)—go to
outline-wiki-uploadSKILL.md - Knowledge bases that are not Outline Wiki(Notion / Confluence / Obsidian / GitHub Wiki)
- Configuration has already succeeded, and only an individual call reports an error—locate it according to the "Troubleshooting" subsection of outline-wiki-search / outline-wiki-upload
Input / Output
Input
At startup, any one of the following authentication materials is required:
- API Key: generated in the Outline Wiki workspace Settings → API , passed via the HTTP header
Authorization: Bearer <key>— suitable for CI / automation / agents in non-interactive mode - OAuth: after adding the MCP endpoint in the client,a browser login window pops up automatically—suitable for interactive scenarios (Claude Code / Claude Desktop)
plus MCP endpoint URL(choose one of the two):
- Official cloud:
https://<your-subdomain>.getoutline.com/mcp - Self-hosted:
https://<your-domain>/mcp(the path is fixed as/mcp)
Output
- Configuration written to(written to disk according to scope):
project(default) → repository root.mcp.json(can be shared with the team via git)user→~/.claude.json#mcpServers(all projects on this machine)local→~/.claude.json#projects.<projectPath>.mcpServers(only this project on this machine)
- First time entering the project: Claude Code pops up a trust prompt once; just approve it as prompted—it pops up only once per project
- Restart the current Claude Code session(hard constraint), after which
/mcpthe list can seeoutline ✓ Connected, and the agent can call themcp__outline__*series of tools
Execution principles / boundaries
Hard constraints that must be followed when running this skill (for detailed reasoning see the paragraph on the right; don't just read this section):
| Principles | Detailed reasoning |
|---|---|
Single controlled entry point—the agent does not directly call claude mcp add, nor directly edit ~/.claude.json or .claude/settings.local.json |
§Workflow / Controlled entry point constraints |
| Restart must be performed by the user—the script will not restart Claude Code on its own | §Design decisions (restart hard constraint) |
scope: choose exactly one, they cannot be mixed——project / user / local different scopes write to different locations |
§Scope selection |
| Diagnostic priority—handshake failure → 401 / 403 → connection refused → not registered → missing after restart | §Troubleshooting |
Design decisions (restart hard constraint)
Restarting Claude Code is a hard constraint. The Outline Wiki MCP server must be registered in
~/.claude.json#mcpServers, and the Claude Code CLI reads it in once at session startup; changing the file mid-session will not be re-read, and there is noclaude mcp reload/claude mcp restart/claude mcp reconnectsubcommand of this kind./mcpThe slash command can reconnect already registeredservers, butwill notload new servers.Therefore: before using this skill,if the outline-related MCP tools are not yet registered in the current session, you must first run the configuration script,then restart the current session(recommended:
claude --continueto continue the history). For the complete process, "why a restart is required," and the post-restart verification checklist, seereferences/onboarding.md。
"Workarounds" that have been considered and why they are also not feasible
| Approach | Problem |
|---|---|
Writing project-level .mcp.json |
is also read at session startup; project-level adds an extra trust prompt—this skill is project-level by default, and this cost has been accepted in exchange for "configuration not spilling over into other projects" |
Run claude mcp serve forwarding |
Using Claude Code itself as a server for forwarding has nothing to do with adding a new server |
Use a script to kill the current process and restart |
The script cannot obtain the user's terminal control, and it also corrupts session state |
mcp-remote proxy |
only converts Streamable HTTP to STDIO, and the session still has to be restarted |
Conclusion:Restarting is a hard constraint of the Claude Code CLI. The job of this skill is to let the userrestart only once、take effect immediately upon restart、be able to verify immediately after restart。
Workflow / Steps
Standard process
- Detect current state: first check whether the
mcp__outline__*tool is already registered in the session- If yes → configuration is complete, prompt the user to go directly to outline-wiki-search / outline-wiki-upload
- If no → enter the guided configuration process
- Collect information: use
AskUserQuestionto guide the user to provide- endpoint type (official cloud / self-hosted)
- actual endpoint domain (subdomain or self-hosted domain)
- authentication material (API key or OAuth)
- Configuration scope (
projectdefault /user/local; seereferences/onboarding.mdQ3)
- Invoke the configuration script: put the collected values into environment variables, call
scripts/configure_mcp.py - Verify registration: the script internally runs
claude mcp get outlineto confirmStatus: ✓ Connected - Prompt the user to restart: print the post-restart verification checklist,do notlet the script restart itself (it would break the session)
- Post-restart verification(performed by the user):
Ctrl+Dexit the current session →claude --continueresume/mcpcheckoutline ✓ Connected- try calling once
mcp__outline__search_documents(any query) to confirm it works - on failure, troubleshoot per
references/onboarding.md"Common Issues"
Most common path (API Key auth, non-interactive mode)
OUTLINE_MCP_ENDPOINT='https://<your-subdomain>.getoutline.com/mcp' \
OUTLINE_MCP_AUTH_METHOD='apikey' \
OUTLINE_MCP_API_KEY='<key>' \
python3 outline-wiki-setup/scripts/configure_mcp.py
After successful execution,you must restart the current Claude Code session, and the new tool will appear in the
mcp__outline__* list.
OAuth auth or prefer to run manually: directly python3 outline-wiki-setup/scripts/configure_mcp.py
run interactive mode, and the script will prompt item by item.
Scope selection
The configuration scope determines where the configuration is written and who can see it. In interactive mode, use the script's
choose_scope() choose one of three; agent-driven collects via Q3 (see
references/onboarding.md) and then passes it in with
OUTLINE_MCP_SCOPE . In non-interactive mode, directly set OUTLINE_MCP_SCOPE:
project(default): current project only, written to the repository root.mcp.json, can be shared with the team via gituser: shared by all projects on this machine, written to~/.claude.json#mcpServerslocal: this machine + current project only, written to~/.claude.json#projects.<projectPath>.mcpServers, not committed to git
Controlled entry point constraints
scripts/configure_mcp.py is the only controlled client configuration entry point。agent do notdirectly
call claude mcp add, and alsodo notdirectly edit ~/.claude.json or
.claude/settings.local.json. The agent is only responsible for:
- Collecting information (endpoint + auth material)
- Assembling environment variables
- Calling
scripts/configure_mcp.py
File writing is done by the script (passing through claude mcp add).
Troubleshooting
Diagnose in the following order:
- Authentication failure (401 / 403)
- API Key: check whether it has expired or been revoked, and have the user regenerate it
- OAuth: have the user go through the authorization flow again (enter
/mcpto trigger)
- MCP not enabled (connection refused)
- Prompt the user to go to the Outline Wiki workspace Settings → AI and confirm the MCP toggle is enabled
- Self-hosted instances require an administrator to enable it in the console
- Initialization handshake failure: response is not JSON-RPC (the endpoint uniformly returns 200 / 0-body empty response)
- Typical scenario: the user's endpoint goes through an intranet tunnel / reverse proxy box (typically like
*.ddnsto.com),HTTP port returns a placeholder 200 +Content-Length: 0for all paths; the real MCP only passes through to the upstream at HTTPS 443 only then reaches upstream - Diagnosis: manually
curl -X POST https://<同 host>:443/mcp(with initialize body) whether it immediately gets an SSE + JSON init response; if HTTPS works immediately, it is confirmed - Fix: rewrite endpoint to
https://<host>/mcpthen rerunscripts/configure_mcp.py - Key tip: this kind of middlebox's HTTP portalwaysreturns an empty 200, regardless of whether authentication is correct or whether the client host is "marked" in the ddnsto console—the mark only makes the HTTPS path take effect
- Deep diagnostic background(why changing authentication / path / Host header doesn't help, and how a protocol-layer
middlebox consumes HTTP traffic) see
references/onboarding.md§FAQ item 3
- Typical scenario: the user's endpoint goes through an intranet tunnel / reverse proxy box (typically like
claude mcp get outlinereturns "not found"- Configuration write failed. Common causes:
- environment variable not passed to the child process (the script only reads
os.environ, shell did not export) claudeCLI not logged in (prompt the user to firstclaude login)- disk write failed (check
~/.claude.jsonpermissions)
- environment variable not passed to the child process (the script only reads
- Configuration write failed. Common causes:
- after restart
/mcpstill cannot see outline- run in the terminal
claude mcp listto see whether it was actually registered - confirm that the user who starts Claude Code is the same as the user who runs the script
(
whoami/$HOMEmatch) - extreme case: delete
~/.claude.jsoninprojects.<projectPath>.mcpServers.outlinesection, rerun the script once
- run in the terminal
- Already Connected but writing a large document is blocked by auto-mode (whitelist missing)
- Symptom: MCP status ✓ Connected, and the agent also confirms it can call tools, but when writing
a large document (≥ 3000 characters, such as
update_document/create_document/create_attachment) there are occasional false-positive blocks - Why + fix + key prohibitions + fallback: see
references/onboarding.md§FAQ item 8 (includes a 15-item tool whitelist JSON snippet, why not write to user-level settings, curl REST API fallback)
- Symptom: MCP status ✓ Connected, and the agent also confirms it can call tools, but when writing
a large document (≥ 3000 characters, such as
Reference examples
Example one: first integration (API Key mode)
User instruction: "Help me integrate our company's outline, the endpoint is https://acme.getoutline.com/mcp,
and the API key is in my environment variable OUTLINE_API_KEY "
Execution:
1. 探测环境变量:bash -lc 'test -n "$OUTLINE_API_KEY" && echo present || echo missing'
→ present
2. 直接调脚本(非交互):
OUTLINE_MCP_ENDPOINT='https://acme.getoutline.com/mcp' \
OUTLINE_MCP_AUTH_METHOD='apikey' \
OUTLINE_API_KEY=$OUTLINE_API_KEY \
python3 outline-wiki-setup/scripts/configure_mcp.py
3. 脚本内部:握手测试 + claude mcp get outline 验证 + 打印 4 步重启清单
4. 让用户 Ctrl+D → claude --continue
5. 用户重启后说"试调 outline 搜索 '测试'",验证生效
Example two: reconnect (already registered but Connected fails)
User instruction: "I configured outline before, but today /mcp shows outline ⏸ Pending approval, and clicking trust doesn't help either"
Execution:
1. 跑 claude mcp get outline 看具体状态
2. 若 Status: ⏸ Pending → 项目级 trust prompt 没批准;让用户到 Claude Code 里
看信任弹窗
3. 若 Status 已 Connected 但调用报错 → 99% 是鉴权问题,重新跑脚本覆盖 key
4. 都不行 → 删掉 projects.<projectPath>.mcpServers.outline 段,重跑配置
Related references
references/onboarding.md— complete onboarding flow (quick entry / prerequisites / guided configuration / post-restart verification checklist / design decisions / FAQ)references/auth.md— authentication methods + multi-client integration commands (Claude Code / Claude Desktop / Cursor)scripts/configure_mcp.py— the only controlled client configuration entry pointoutline-wiki-searchSKILL.md — companion: search / read outline documentsoutline-wiki-uploadSKILL.md — companion: write / edit outline documents