SuperAPI AI Directory

outline-wiki-setup

General & other

View repository

Updated 10-16 08:44

About this skill

Outline Wiki Setup

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/mcp or https://<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-search SKILL.md
  • Write / edit outline documents(including image attachments / @mention / comments / Collection management / move / delete)—go to outline-wiki-upload SKILL.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/mcp the list can see outline ✓ Connected, and the agent can call the mcp__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 no claude mcp reload / claude mcp restart / claude mcp reconnect subcommand of this kind. /mcp The 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 --continue to continue the history). For the complete process, "why a restart is required," and the post-restart verification checklist, see references/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

  1. 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
  2. Collect information: use AskUserQuestion to 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 (project default / user / local; see references/onboarding.md Q3)
  3. Invoke the configuration script: put the collected values into environment variables, call scripts/configure_mcp.py
  4. Verify registration: the script internally runs claude mcp get outline to confirm Status: ✓ Connected
  5. Prompt the user to restart: print the post-restart verification checklist,do notlet the script restart itself (it would break the session)
  6. Post-restart verification(performed by the user):
    • Ctrl+D exit the current session → claude --continue resume
    • /mcp check outline ✓ 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 git
  • user: shared by all projects on this machine, written to ~/.claude.json#mcpServers
  • local: 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:

  1. Collecting information (endpoint + auth material)
  2. Assembling environment variables
  3. Calling scripts/configure_mcp.py

File writing is done by the script (passing through claude mcp add).

Troubleshooting

Diagnose in the following order:

  1. 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 /mcp to trigger)
  2. 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
  3. 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>/mcp then rerun scripts/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
  4. claude mcp get outline returns "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)
      • claude CLI not logged in (prompt the user to first claude login)
      • disk write failed (check ~/.claude.json permissions)
  5. after restart /mcp still cannot see outline
    • run in the terminal claude mcp list to 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 / $HOME match)
    • extreme case: delete ~/.claude.json in projects.<projectPath>.mcpServers.outline section, rerun the script once
  6. 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)

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 point
  • outline-wiki-search SKILL.md — companion: search / read outline documents
  • outline-wiki-upload SKILL.md — companion: write / edit outline documents