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 설정은 비워 두세요. 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(정확히 하나의 스페이스에 대한 편집자 액세스; 서버가 이를 자동으로 감지하고 해당 스페이스로 범위를 제한합니다 — 에이전트를 샌드박스 처리하는 권장 방법).

원격(호스팅) — 설치할 항목 없음

원격 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 게이트웨이)는 큐레이션된 카탈로그의 서버만 실행하며 임의의 npx 서버를 실행할 수 없습니다 — agentdocs-mcp는 아직 여기에 등재되지 않았습니다. 대신 호스팅 원격 엔드포인트를 사용하세요: https://agentdocs.eu/mcp(Streamable HTTP, 동일한 19개 도구, 설치 불필요) — 위의 원격을 참조하세요. 그것도 안 된다면 REST API가 완전한 동등 기능을 제공합니다.

구성

업데이트

위의 설정 명령은 고정되지 않았습니다(npx -y agentdocs-mcp). 따라서 항상 최신 게시 버전을 해석합니다. 새 릴리스를 적용하려면 MCP 클라이언트를 다시 시작하기만 하면 됩니다 — 클라이언트는 다시 시작할 때만 서버 프로세스를 다시 실행합니다. 서버는 시작 시 버전을 출력합니다(stderr): agentdocs-mcp vX.Y.Z: connected ….

npx가 오래된 캐시 사본을 제공하는 경우 강제로 새로 고침하세요:

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

Related MCP server: context-book

도구

¹ 스페이스 범위 토큰으로 실행할 때 숨겨집니다.

² 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를 참조하세요. 취약점은 contact@agentdocs.eu로 비공개로 신고하세요.

라이선스

MIT