agentdocs-mcp

agentdocs-mcp

AgentDocs 用の MCP サーバーです。AI エージェントを中核的な利用者として迎える、共同ドキュメント作成プラットフォームです。

ローカルサーバーを実行する MCP クライアント（Claude Code、Claude Desktop、Cursor、Windsurf、Zed、…）に、AgentDocs のページを読み取り、検索、作成、更新、共有するためのネイティブツールを提供します。

Claude.ai（ウェブ）、Claude Desktop、Claude モバイルは、トークンなしで接続できます。 カスタムコネクターとして https://agentdocs.eu/mcp を追加し（Settings → Connectors → Add custom connector）、Advanced settings は空のままにしてください。AgentDocs は OAuth 2.1 を実装しているため、Claude がフローを自動的に検出します。ブラウザーで AgentDocs の同意ページが開き、承認すると接続されます。許可の対象はご自身のドキュメントのみで、いつでも agentdocs.eu → Settings → Connected apps から取り消せます。ホスト型の Skill はコネクター不要の代替手段です。また、Claude Desktop では、下記のローカル stdio 設定も使用できます。

公式 MCP レジストリには io.github.hoornet/agentdocs-mcp として掲載されています。

セットアップ

MCP コネクタークライアント（Claude.ai / Desktop / モバイル）にはトークンは不要です。上記の OAuth に関する説明をご覧ください。ローカル stdio サーバーやその他のクライアントでは、AgentDocs API トークンが必要です。

• アカウントトークン — agentdocs.eu → Profile → Regenerate API Token（所有するすべてのものへのフルアクセス）、または
• スペーストークン — Space settings → Tokens（特定の 1 つのスペースへの編集アクセス。サーバーはこれを自動検出して、そのスペースにスコープを限定します。エージェントを隔離する場合に推奨される方法です）。

リモート（ホスト型）— インストール不要

リモート MCP に対応するクライアントであれば、ホスト型エンドポイントを直接使用できます。インストールするパッケージはなく、更新も不要です。stdio サーバーと同じ 19 個のツールを利用できます。

https://agentdocs.eu/mcp        (Streamable HTTP)
Authorization: Token <your-token>   # or no header at all — OAuth clients authenticate via the built-in flow

# Claude Code
claude mcp add --transport http agentdocs https://agentdocs.eu/mcp \
  --header "Authorization: Token <your-token>"

Claude.ai（ウェブ）と Claude Desktop は、どちらも同じ手順で設定します。Settings → Connectors → Add custom connector を開き、Authorization リクエストヘッダーを設定してください。

このリクエストヘッダー欄は Anthropic のベータ機能で、アカウントごとに有効化されます。Advanced settings に OAuth Client ID と OAuth Client Secret しか表示されない場合、そのアカウントではこの機能を利用できません。また、ここでは OAuth フィールドは機能しません。AgentDocs はまだ OAuth を実装していないためです（実装予定）。コネクターは接続エラーを報告します。

その場合は Skill（Skills → Upload Skill）を使用してください。ベータ機能へのアクセスは不要で、同じ REST API を利用でき、現在の Claude.ai ではこちらが確実な方法です。

Bearer <api_token> は Token <api_token> と同様に使用できます。複数のクライアントが「Bearer」フィールドしか提供していないためです。アカウントトークンとスペーススコープのトークンの両方を使用できます。スペーストークンを使うと、REST と同じように、セッションをそのトークンが属するスペース内に限定できます。

Claude Code（ローカル stdio）

claude mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp

Codex CLI

codex mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp

または、~/.codex/config.toml に設定します。

[mcp_servers.agentdocs]
command = "npx"
args = ["-y", "agentdocs-mcp"]
[mcp_servers.agentdocs.env]
AGENTDOCS_TOKEN = "<your-token>"

Claude Desktop / Cursor / Windsurf / Gemini CLI / 汎用 MCP 設定

それぞれ、claude_desktop_config.json / .cursor/mcp.json / ~/.codeium/windsurf/mcp_config.json / ~/.gemini/settings.json に設定します。

{
  "mcpServers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

VS Code（Copilot）

同じサーバーブロックを使用しますが、.vscode/mcp.json ではトップレベルの "servers" キーを使います。

{
  "servers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

Zed

settings.json に設定します。

{
  "context_servers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

Opencode

（プロジェクトルートの）opencode.json または ~/.config/opencode/opencode.json に設定します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentdocs": {
      "type": "local",
      "command": ["npx", "-y", "agentdocs-mcp"],
      "environment": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

pi / oh-my-pi

ベースの pi には MCP サポートが含まれていません。Skill または通常の REST API をご利用ください。 oh-my-pi（omp）フォークは MCP をサポートしており、ディスク上にある設定（.claude、.cursor、.codex、 .vscode、…）からサーバー設定を引き継ぎます。上記の標準的な mcpServers ブロックをそのいずれか（例： .cursor/mcp.json）に追加し、omp を再起動してください。

Windows

多くの MCP クライアントでは、Windows 上で npx を直接起動できません（spawn npx ENOENT）。 コマンドを cmd /c でラップしてください。

"command": "cmd",
"args": ["/c", "npx", "-y", "agentdocs-mcp"]

カタログベースの MCP ゲートウェイ（Docker MCP gateway など）は、厳選されたカタログにあるサーバーのみを実行でき、任意の npx サーバーを起動できません。agentdocs-mcp はまだカタログに掲載されていません。代わりに、ホストされたリモートエンドポイント（https://agentdocs.eu/mcp）（Streamable HTTP、同じ 19 個のツール、インストール不要）を使用してください。上記のリモートを参照してください。利用できない場合は、REST APIでも同じ機能を利用できます。

設定

環境変数	デフォルト	用途
AGENTDOCS_TOKEN	~/.config/agentdocs/token の内容	API トークン（アカウントまたはスペースのスコープ）
AGENTDOCS_URL	https://agentdocs.eu	API のベース URL を上書きします。高度な設定です。別のエンドポイントを指定された場合にのみ設定してください

更新

上記のセットアップコマンドはバージョンを固定していないため（npx -y agentdocs-mcp）、常に公開済みの最新バージョンが解決されます。新しいリリースを適用するには、MCP クライアントを再起動するだけです。クライアントは再起動時にのみサーバープロセスを再起動します。起動時にサーバーのバージョンが stderr に出力されます：agentdocs-mcp vX.Y.Z: connected …。

npx が古いキャッシュを使用している場合は、強制的に更新してください。

npx -y agentdocs-mcp@latest    # or: npm cache clean --force

ツール

ツール	説明
whoami	ユーザーと認証情報のスコープを確認します
list_workspaces	アクセス可能なワークスペースを一覧表示します ¹
list_spaces	ワークスペース内のスペースを一覧表示します ¹
list_pages	スペースのページツリーを表示します（コンテンツなし）
search_docs	ワークスペース全体を全文（キーワード）検索します ¹
semantic_search	意味に基づいて順位付けされた自然言語検索です — Pro ワークスペース向け ¹
get_page	ページを読み取ります（Markdown 全文とバージョン）。オプションで include_comments ／ include_children ／ include_images を指定できます（埋め込み画像を表示可能な画像ブロックとして返します）
create_page	Markdown ページを作成します（入れ子にできます）
update_page	タイトルやコンテンツを更新します。オプションで楽観的バージョンチェックを指定できます
append_to_page	Markdown を追記します — ログやセッションレポートに最適です
import_markdown	Markdown ファイルのフォルダーをインポートします。パスがページ階層になります。冪等です — 再インポート時はソースパスを基に既存ページを再利用するため、重複しません。parent_page アンカーと overwrite_existing により再同期します
delete_page	ページを削除します（子ページも連鎖的に削除されます）
bulk_create_pages	明示的な構造を指定して、最大 500 ページをアトミックに作成します
share_page	公開マジックリンクを作成します（Web と raw-Markdown の URL）
list_comments	ページのスレッド形式のコメント（ID、投稿者、親）を一覧表示します
add_comment	コメントまたはスレッドへの返信を投稿します（@mentions を使用できます）
update_comment	コメントを編集するか、スレッドを解決済みとしてマークします（投稿者／管理者）
delete_comment	コメントを削除します（投稿者／管理者）
upload_image	PNG／JPEG／GIF／WebP をスペースに添付し、埋め込み用の Markdown を取得します — path ²、source_url、または base64 の data から指定できます

¹ スペーススコープのトークンで実行している場合は非表示になります。

² path はこのサーバーを実行しているマシン上のファイルを読み取るため、stdio サーバーでのみ機能します。ホストされた agentdocs.eu/mcp エンドポイントでは受け付けられません。そこでは「マシン」が AgentDocs の本番サーバーであり、呼び出し元が指定したパスを許可すると任意のファイル読み取りが可能になるためです。その場合は source_url または data を使用してください。

ページ、スペース、ワークスペースは UUID または人が読みやすいスラッグパスで指定できます — get_page では "my-workspace/my-space/my-page"、create_page では "my-workspace/my-space" などを指定できます（スラッグパスにはアカウントトークンが必要です）。

注意事項

• ページを更新するたびにサーバー上にバージョンが作成されます。古いバージョンは AgentDocs UI から引き続き復元できます。
• ホストされたインスタンスは、アイドル状態の後に最初のリクエストへ応答するまで約 15 秒かかる場合があります（データベースのコールドスタート）。サーバーは 35 秒のタイムアウトと 1 回の再試行でこれに対応します。
• 無料プランの API 制限は、アップグレードリンク付きの明確なメッセージで通知されます。

開発

npm install
npm run build

# End-to-end smoke tests (hit a real AgentDocs instance with YOUR data):
SMOKE_TESTBED_SPACE="workspace-slug/scratch-space-slug" \
SMOKE_KNOWN_PAGE="workspace-slug/space-slug/page-slug" \
node test/smoke.mjs                       # account token: all tools

AGENTDOCS_TOKEN=<space-token> node test/smoke-space-token.mjs   # space-token mode

テスト用スペースに書き込み（ページの作成と削除）を行います。スクラッチスペースを使用してください。

セキュリティ

SECURITY.md を参照してください。脆弱性は [email protected] まで非公開で報告してください。

ライセンス

MIT