AI 앱 연결

MCP는 AI 앱이 다른 프로그램의 도구를 쓰는 표준 연결 방식입니다. AI 앱은 실행 중인 dtxWiki 서버에 접속해 허용된 지식을 검색하고, 필요한 권한이 있으면 변경을 제안할 수 있습니다. 데이터베이스를 직접 열지는 않습니다. dtxWiki 서버가 계속 실행되어 있어야 합니다.

앱의 요청 → dtxWiki의 접근 확인 → 허용된 결과 반환으로 읽으면 됩니다. 외부 앱에 반환된 자료는 해당 모델 제공자가 처리할 수 있습니다. 이 도표는 접근 경계의 설명이며, 실제 연결 상태나 자동 실행을 표시하지 않습니다.

AI 앱 없이 브라우저에서 dtxWiki를 사용할 수 있습니다. AI 앱 자체의 설치·계정·구독·모델 사용은 dtxWiki와 별개입니다. 앱을 연결해도 dtxWiki의 선택적 질문 모델 제공자가 켜지지는 않습니다.

연결 전 준비

dtxWiki 계정, 필요한 워크스페이스 멤버십, 서버의 MCP 주소가 필요합니다. 원격 서버는 보통 https://wiki.example.com/mcp 형태입니다.

패키지의 클라이언트 목록에는 Claude Code, Codex CLI, Gemini CLI, Google Antigravity가 있습니다. Cursor 등은 Streamable HTTP와 PAT 또는 OAuth 인증을 지원할 때 수동 HTTP 설정을 사용할 수 있습니다. 모든 클라이언트·버전 조합이 실제 연동 검사를 완료했다는 뜻은 아닙니다.

설정 생성과 서버 동작의 검증은 클라이언트 자체의 전체 연동 검증과 별개이며, 전체 연동은 호환성 표에서 검증 대기로 남아 있습니다. 실제 환경에서 필요한 자료를 읽을 수 있는지 확인한 뒤 연결을 사용하세요.

필요한 최소 접근부터 선택하세요. 권한 범위(scope)는 자격 증명이 사용할 도구 종류를 제한합니다. 워크스페이스 멤버십·역할도 함께 검사합니다. 읽기 키는 쓰기를 허용하지 않으며, 뷰어가 강한 키를 요청해도 편집자 권한을 얻지는 않습니다.

VS Code 안에서 Codex나 Claude Code를 사용한다면 액세스 키를 만든 뒤 VS Code 확장 연결을 따르세요. 별도 CLI를 설치하지 않고 설정 파일을 편집할 수도 있습니다. 이전에 export로 연결했다가 재시작 후 끊겼다면 확장을 다시 켜기 전에 환경 변수 저장을 진행하세요.

방법 A: OAuth로 브라우저 승인

OAuth는 PAT를 직접 복사하지 않고 브라우저에서 앱 접근을 승인하는 방식입니다. 서버와 앱이 지원하면 사용하고, 그렇지 않으면 방법 B를 따릅니다. 서버는 HTTPS가 필요합니다. 내부 CA에서는 브라우저와 앱에 root 인증서 신뢰를 설정해야 합니다.

설정 → MCP 접근에서 OAuth 사용 가능 여부를 확인합니다. 이 서버가 OAuth를 제공할 수 없으면 안내에 표시되는 Access Key를 사용하세요. 링크로 액세스 키 설정(방법 B)에 바로 이동할 수 있습니다.
화면에 표시된 AI 클라이언트 연결 명령을 선택하거나 해당 앱에서 dtxWiki HTTPS MCP 주소를 추가합니다.
앱의 로그인 안내를 따릅니다. 브라우저 동의 화면에서 계정·허용 워크스페이스·권한 범위를 확인한 뒤 승인합니다.
앱으로 돌아와 아래 실제 읽기 검사를 진행합니다.
OAuth 앱의 승인된 앱에 연결이 표시되는지 확인합니다. 이후 워크스페이스 편집으로 접근 범위를 바꾸거나 해지로 연결 승인을 제거합니다.

앱 카드에는 이름 옆의 상태와 권한, 허용 Workspace가 표시됩니다. 허용 워크스페이스는 이름이 최대 두 개까지 보이고, 더 있으면 +N개가 붙습니다. 이름이나 +N개를 누르면 검색할 수 있는 전체 목록이 열립니다. 그 아래에는 승인일, 최근 사용, 세션 만료가 있습니다. 남은 로그인 세션이 없으면 세션 만료에 재승인 필요가 표시되므로, 계속 쓰려면 앱에서 다시 로그인해 승인하세요.

이 소스가 확인한 CLI의 등록·로그인 문법은 다음과 같습니다.

# Claude Code
claude mcp add --scope user --transport http dtxwiki https://wiki.example.com/mcp
claude mcp login dtxwiki

# Codex CLI
codex mcp add dtxwiki --url https://wiki.example.com/mcp --oauth-client-registration auto
codex mcp login dtxwiki --oauth-client-registration auto

명령 문법 확인과 브라우저 승인·갱신·인증된 도구 호출 검증은 별개입니다. 설치한 클라이언트에서 실제로 확인하세요. v0.2.1에는 Gemini CLI와 Antigravity의 완료된 dtxWiki OAuth 연동 근거가 없으므로 환경이 검증되기 전에는 PAT를 사용합니다. 서버가 자동 클라이언트 등록을 닫았다면 호환되는 HTTPS URL 클라이언트 식별자를 사용하거나 설정 화면이 안내하는 액세스 키 경로를 따릅니다.

방법 B: 액세스 키 만들기

액세스 키는 내 계정으로 앱이 작업하도록 허용하는 비밀값인 Personal Access Token(PAT)입니다.

설정 → MCP 접근의 액세스 키 설정을 엽니다.
클라이언트를 선택하고 “연구 노트북”처럼 알아보기 쉬운 키 이름을 입력합니다. 이름은 한 줄로 최대 128자까지 쓸 수 있습니다. 기타 MCP 클라이언트를 고르면 AI 앱 표시 이름(최대 160자)도 입력합니다.
이 키가 접근할 워크스페이스에는 기본 워크스페이스가 미리 선택되어 있습니다. 선택을 바꾸려면 전체 목록 보기·선택을 누릅니다. 허용된 워크스페이스 대화 상자에서는 다음과 같이 고릅니다.
- 워크스페이스 이름이나 슬러그로 검색합니다. 목록에는 내가 멤버인 워크스페이스만 기본 워크스페이스부터 한 페이지에 8개씩 나오며, 이전·다음으로 페이지를 넘깁니다.
- 행을 눌러 선택하거나 해제합니다. 이 페이지 전체 선택은 현재 페이지의 워크스페이스를 한꺼번에 선택하거나 해제하고, 전체 선택 지우기는 모든 선택을 지웁니다. 선택한 항목 (N개) 버튼은 선택한 항목만 보여 주고, 전체 Workspace 보기 (N) 버튼은 전체 목록으로 돌아갑니다.
- N개 선택 적용을 누르면 선택이 반영되고, 취소를 누르면 변경 내용을 버립니다. 키 하나는 최대 256개 워크스페이스에 접근할 수 있습니다.
화면의 읽기(Read)·쓰기(Write)·AI 실행(Run AI) 권한을 검토합니다. 지식 검색은 읽기로 시작하고, Context 편집과 참고문헌 등록은 쓰기 및 편집자·소유자 멤버십이 필요합니다. AI 실행만으로 Context를 편집할 수는 없습니다.
액세스 키 생성을 누르고 키가 한 번 표시될 때 복사한 뒤 앱 설정을 따릅니다. 공개 저장소·이슈·화면 캡처에 키를 남기지 마세요.

설정 화면에서 만든 키는 90일 뒤 만료되며, 다른 만료 기간을 고르는 항목은 없습니다.

검색하거나 페이지를 넘겨도 이미 선택한 워크스페이스는 유지됩니다. 적용하기 전에 선택한 항목 (N개)에서 전체 선택을 확인하세요. 대화 상자에 Workspace를 불러오지 못했습니다.가 나오면 다시 시도를 누르고 결과가 표시된 뒤 접근 범위를 바꾸세요.

키의 허용 워크스페이스는 현재 화면의 공간만이 아닌 계정 전체에서 선택합니다. 나중에 앱을 다시 등록하지 않고 바꾸려면 키 카드의 워크스페이스 편집을 누릅니다. 키 이름이 붙은 …의 워크스페이스 대화 상자에서 같은 방식으로 검색하고 페이지를 넘길 수 있으며, 상태 줄에 추가·제거한 워크스페이스 수가 표시됩니다. 제거한 워크스페이스에는 즉시 접근할 수 없게 되고, 진행 중인 편집본은 보존됩니다. 워크스페이스 저장은 선택이 바뀌었고 비어 있지 않을 때만 누를 수 있습니다. 더 이상 멤버가 아닌 워크스페이스는 선택한 항목에서 멤버십 없음으로 표시되며 제거만 할 수 있습니다. OAuth 앱도 같은 대화 상자를 사용합니다.

계정이 멤버인 것만으로는 충분하지 않습니다. 자격 증명에 없는 공간을 요청하면 token_workspace_denied가 반환됩니다.

앱별 직접 등록 예시

실제 서버 주소와 자격 증명으로 바꿉니다. 아래 자리표시자는 사용할 수 있는 토큰이 아닙니다. 서버와 선택한 shell을 반영하는 설정 화면의 생성 명령을 우선 사용하세요.

Claude Code는 bearer header를 사용하면 로컬 설정에 PAT를 보관합니다.

claude mcp add --scope user --transport http dtxwiki https://wiki.example.com/mcp \
  --header "Authorization: Bearer <YOUR_DTXWIKI_PAT>"

Codex CLI는 환경 변수에서 PAT를 읽습니다. 아래 Bash 예시는 현재 터미널과 여기서 실행하는 앱에만 적용됩니다. 실제 값을 명령 이력에 넣지 않고 입력할 수 있습니다.

read -r -s -p 'dtxWiki access key: ' DTXWIKI_MCP_PAT
printf '\n'
export DTXWIKI_MCP_PAT
codex mcp add dtxwiki --url https://wiki.example.com/mcp \
  --bearer-token-env-var DTXWIKI_MCP_PAT

등록 명령은 변수 이름을 저장하며 실제 값은 저장하지 않습니다. 이 터미널에서 codex를 실행하면 임시 값을 사용할 수 있습니다. 터미널을 닫거나 컴퓨터를 재시작하면 이 값은 사라집니다. 다음 실행에도 사용하려면 환경 변수 저장을 따르세요. 조직에서 비밀값 관리 도구를 제공한다면 그 도구가 지원하는 변수 전달 방식을 사용합니다.

Gemini CLI는 header 설정에 환경 변수 참조를 저장합니다. DTXWIKI_MCP_PAT가 환경에 준비되어 있을 때:

gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer $DTXWIKI_MCP_PAT' \
  dtxwiki https://wiki.example.com/mcp

작은따옴표는 $DTXWIKI_MCP_PAT를 Gemini의 설정 문자열에서 해석하도록 보존합니다. JSON의 HTTP 주소 필드는 httpUrl입니다.

Google Antigravity는 아래 도우미 또는 ~/.gemini/config/mcp_config.json의 HTTP 항목으로 설정합니다.

{
  "mcpServers": {
    "dtxwiki": {
      "serverUrl": "https://wiki.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DTXWIKI_PAT>"
      }
    }
  }
}

기존 설정에 항목을 합치고 다른 서버를 지우지 마세요. 이 방식은 PAT를 평문으로 저장하므로 파일과 백업을 보호합니다. 저장된 Antigravity header 안의 $VAR 확장은 검증되지 않았습니다. 재시작 후 앱의 /mcp에서 상태를 보고 실제 읽기를 검사하세요.

Cursor와 다른 HTTP 클라이언트는 해당 앱이 받아들이는 경우 다음 구조를 사용할 수 있습니다.

{
  "mcpServers": {
    "dtxwiki": {
      "url": "https://wiki.example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <YOUR_DTXWIKI_PAT>"
      }
    }
  }
}

Windows와 설정 위치

설정 화면의 Windows 명령을 사용하세요. PowerShell의 여러 줄 명령은 backtick을 사용하며 Bash의 역슬래시와 같지 않습니다. 환경 변수를 사용하는 앱은 먼저 Windows 사용자 변수 저장을 진행하세요. 변수를 준비했다면 Codex 등록 명령은 PowerShell에서 한 줄로 입력할 수 있습니다.

codex mcp add dtxwiki --url https://wiki.example.com/mcp --bearer-token-env-var DTXWIKI_MCP_PAT

앱	기본 사용자 설정
Claude Code	`~/.claude.json`. Windows: `%USERPROFILE%\.claude.json`
Codex CLI	`~/.codex/config.toml`. `CODEX_HOME`이 설정되면 `$CODEX_HOME/config.toml`
Gemini CLI	`~/.gemini/settings.json`. Windows: `%USERPROFILE%\.gemini\settings.json`
Antigravity	`~/.gemini/config/mcp_config.json`. Windows: `%USERPROFILE%\.gemini\config\mcp_config.json`

앱 자체의 등록 명령에는 내 컴퓨터의 dtxWiki Python 패키지가 필요하지 않습니다.

VS Code 확장 연결

VS Code의 확장(Extensions) 화면을 엽니다(Windows/Linux: Ctrl+Shift+X, macOS: Cmd+Shift+X). OpenAI의 공식 Codex 확장이나 Anthropic의 Claude Code 확장을 설치하고, 확장 패널에서 로그인을 마칩니다. 이 계정 로그인과 dtxWiki 액세스 키는 각각 별도로 필요합니다. 설치 안내: Codex IDE 확장, VS Code의 Claude Code.

사용하는 확장에 맞는 절차를 선택하세요. 각 확장은 자체 MCP 설정을 읽습니다. Copilot용 VS Code 기본 MCP 설정은 별도로 관리됩니다.

Codex 확장

위에서 액세스 키를 만든 뒤 환경 변수 저장을 완료합니다. 확장이 실행되는 환경에 맞춰 Windows, macOS/Linux 또는 WSL 절차를 선택하세요.
VS Code에서 사용자 설정 파일을 엽니다. macOS/Linux는 ~/.codex/config.toml, Windows는 %USERPROFILE%\.codex\config.toml입니다. ~와 %USERPROFILE%은 내 사용자 홈 폴더를 뜻합니다. 폴더나 파일이 없으면 만드세요. CODEX_HOME을 지정했다면 그 폴더 안의 config.toml을 사용합니다.
다음 내용을 추가하고 저장합니다. [mcp_servers.dtxwiki]가 이미 있다면 같은 블록을 두 번 만들지 말고 기존 항목을 수정합니다. 다른 설정은 유지하고 예시 서버 주소를 실제 주소로 바꾸세요.

[mcp_servers.dtxwiki]
url = "https://wiki.example.com/mcp"
bearer_token_env_var = "DTXWIKI_MCP_PAT"

VS Code를 완전히 종료한 뒤 환경 변수 안내에 따라 저장한 변수를 사용할 수 있는 상태에서 다시 실행합니다. Codex 패널의 MCP 서버 목록을 확인하고 아래 실제 읽기 검사를 진행합니다.

CLI와 확장이 같은 컴퓨터에서 같은 사용자·Codex 홈을 사용하면 MCP 설정을 공유합니다. 이미 codex mcp add를 실행했다면 기존 항목을 확인하세요. 위 TOML 항목에는 변수 이름만 들어 있으며, 확장을 시작할 때마다 실제 값도 필요합니다. OpenAI의 MCP 설정 문서를 참고하세요.

Claude Code 확장

이미 claude mcp add --scope user ... --header "Authorization: Bearer <YOUR_DTXWIKI_PAT>"로 등록했다면 확장에서 새 대화를 시작하고 /mcp를 확인합니다. 이 방식은 로컬 사용자 설정에 실제 키를 저장하므로 매번 환경 변수를 준비하지 않아도 됩니다. 해당 파일을 보호하세요.

키를 프로젝트 설정에 넣지 않고 환경 변수에서 읽게 하려면 다음과 같이 진행합니다.

Claude Code가 실행되는 환경에서 환경 변수 저장을 완료합니다.
VS Code에서 신뢰하는 프로젝트를 엽니다. README.md 등이 있는 프로젝트의 최상위 폴더에 .mcp.json 파일을 만듭니다. 맨 앞의 점도 파일 이름에 포함됩니다. 파일이 이미 있다면 기존 mcpServers 안에 dtxwiki 항목을 합칩니다.
다음 설정의 서버 주소를 실제 주소로 바꾸고 저장합니다. ${DTXWIKI_MCP_PAT}는 그대로 두세요. Claude Code가 설정을 읽을 때 환경 변수의 값으로 바꿉니다.

{
  "mcpServers": {
    "dtxwiki": {
      "type": "http",
      "url": "https://wiki.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DTXWIKI_MCP_PAT}"
      }
    }
  }
}

VS Code를 완전히 종료한 뒤 변수가 준비된 상태에서 다시 실행합니다. 같은 프로젝트를 열고 Claude Code에서 새 대화를 시작합니다. 프로젝트 서버 승인 안내가 나오면 내용을 확인한 뒤 허용하세요. /mcp로 dtxWiki 상태를 보고 아래 실제 읽기 검사를 진행합니다.

이 .mcp.json은 해당 프로젝트에 적용됩니다. 같은 이름의 로컬·사용자 등록이 있으면 그 설정이 우선할 수 있으므로, 바꾸기 전에 /mcp에서 사용 중인 설정을 확인하세요. ${DTXWIKI_MCP_PAT} 자리에 실제 키를 붙여넣으면 파일에 비밀값이 저장됩니다. 또한 --header "Authorization: Bearer $DTXWIKI_MCP_PAT"처럼 명령에 쓰면 셸이 먼저 실제 값으로 바꾸므로 등록된 설정에는 실제 키가 들어갑니다. Claude Code의 설정 범위와 변수 치환을 참고하세요.

두 확장 모두 VS Code 내장 터미널에서 변수를 설정하면 그 터미널에서 실행하는 명령에만 전달됩니다. 이미 실행 중인 확장에는 반영되지 않습니다. CLI는 되지만 확장에서 실패한다면 VS Code 실행 절차를 따르세요.

선택 사항: dtxWiki 설정 도우미

같은 버전의 dtxWiki 패키지를 설치했다면 지원되는 로컬 클라이언트 설정을 백업하고 갱신하는 도우미를 사용할 수 있습니다. 목록 ID는 claude-code, codex, gemini-cli, antigravity 중 하나입니다.

dtxwiki mcp register-http \
  --url https://wiki.example.com/mcp \
  --client codex \
  --token-env DTXWIKI_MCP_PAT

--dry-run을 추가하면 파일을 바꾸지 않고 확인합니다. 도우미는 설정을 변경했는지 또는 안내만 생성했는지 표시합니다. 일부 앱에는 평문 PAT가 저장되므로 경고를 읽고 파일을 보호하세요. --token으로 넘기면 프로세스 인자에 노출될 수 있어 --token-env를 권장합니다.

도우미는 이미 준비된 변수를 읽으며, 다음 터미널이나 컴퓨터 재시작을 위해 변수를 저장하지는 않습니다. Codex에 쓰는 설정도 여전히 DTXWIKI_MCP_PAT를 참조하므로 환경 변수 저장도 완료하세요.

일반 HTTP: 이 컴퓨터 또는 신뢰하는 LAN

도우미는 --allow-insecure-local을 추가하지 않으면 일반 http:// 주소를 거부합니다. 이 옵션을 써도 액세스 키(--token-env 또는 --token)가 필요하며, 다음 호스트만 받습니다.

이 컴퓨터: localhost, [::1], 또는 127.0.0.1 같은 127.x.x.x 주소
숫자로 쓴 사설 네트워크 IP 주소: 10.x.x.x, 172.16.x.x~172.31.x.x, 192.168.x.x, 또는 fc00::/7 범위의 IPv6 주소

wiki.lan 같은 호스트 이름과 그 밖의 모든 주소에는 여전히 HTTPS가 필요합니다. OAuth는 항상 HTTPS가 필요합니다.

동일 컴퓨터의 로컬 체험에서는 다음과 같이 등록합니다.

dtxwiki mcp register-http \
  --url http://127.0.0.1:21080/mcp \
  --client codex \
  --token-env DTXWIKI_MCP_PAT \
  --allow-insecure-local

이 주소는 dtxWiki가 실행 중인 컴퓨터에서만 사용할 수 있습니다. 신뢰하는 LAN에서 체험할 때는 다른 컴퓨터에서 서버의 사설 IP 주소로 도우미를 실행합니다. 예를 들어 LAN 접속 안내대로 서버를 시작했다면 다음과 같습니다.

dtxwiki mcp register-http \
  --url http://192.168.1.20:21080/mcp \
  --client codex \
  --token-env DTXWIKI_MCP_PAT \
  --allow-insecure-local

일반 HTTP는 액세스 키와 반환되는 모든 페이지를 암호화하지 않고 보냅니다. 신뢰하는 네트워크에서 평가할 때만 사용하세요. DTXWIKI_PUBLIC_BASE_URL을 이런 사설 IP 주소로 설정하면 설정 → MCP 접근의 액세스 키 설정도 Claude Code, Codex CLI, Gemini CLI, Antigravity에 같은 HTTP 주소를 표시합니다. 기타 MCP 클라이언트에는 여전히 HTTPS가 필요합니다. dtxwiki mcp doctor --http도 이런 주소를 받지만 http://에서는 [b] tls handshake 검사가 항상 실패하므로, [d] list_tools가 통과해도 보고서는 one or more checks failed로 끝납니다. 인터넷을 거쳐 연결하는 앱에는 서버의 HTTPS 주소가 필요합니다.

권한을 늘리기 전에 실제 연결 검사

다음과 같이 앱에 요청합니다.

“dtxWiki로 내가 접근 가능한 워크스페이스 목록을 보여줘. 프로젝트 공간에서 회의 절차에 관한 발행된 페이지를 찾아 제목과 출처를 알려줘. 내용은 수정하지 마.”

브라우저에서 읽을 수 있는 공간과 내용이 맞는지 확인합니다. 나중에 쓰기를 허용한다면 연습 공간에서 이름을 명확히 정한 초안을 만들어 보고 브라우저에서 편집·검토 상태를 확인하세요. 편집자와 소유자는 채팅에서 앱의 호출을 선택한 뒤 입력 탭에서 사용한 워크스페이스와, 표시되는 경우 페이지 버전(입력 버전, 기준 버전)도 확인할 수 있습니다. 등록 항목·연결 표시·서버 doctor 성공만으로 실제 읽기나 안전한 편집을 증명하지는 않습니다.

설정에서 연결 상태 확인

설정 → MCP 접근의 연결된 MCP 클라이언트 카드는 현재 선택한 워크스페이스를 호출한 클라이언트 신원을 보여 줍니다. 다른 워크스페이스의 클라이언트를 보려면 워크스페이스를 바꾸세요. 각 클라이언트 이름 옆에는 그 클라이언트가 사용한 자격 증명, 즉 액세스 키나 OAuth 승인의 상태가 표시됩니다.

상태	의미
인증 유효	액세스 키나 OAuth 승인이 이 워크스페이스에서 아직 유효합니다.
인증 만료	키의 만료일이 지났거나 OAuth 승인에 남은 세션이 없습니다.
인증 취소	키나 OAuth 승인이 취소되었거나, 이 워크스페이스가 허용 목록에서 빠졌거나, 자격 증명을 가진 사용자가 더 이상 이 워크스페이스의 활성 멤버가 아닙니다.
인증 상태 확인 필요	클라이언트가 사용한 자격 증명을 dtxWiki가 알 수 없거나 그 자격 증명이 더 이상 없습니다. 이전 기록은 클라이언트의 다음 호출 때 채워집니다.
사용 차단	소유자가 클라이언트를 비활성화했습니다. 이때는 자격 증명 상태 대신 이 표시가 나옵니다.

별도 줄에는 소유자의 설정인 사용 허용 또는 사용 차단이 표시됩니다. 시간 정보에는 최근 사용과 함께 액세스 키는 키 만료일, OAuth는 세션 만료가 나오며, 남은 세션이 없으면 재승인 필요로 표시됩니다.

MCP 클라이언트 상태 필터로 사용 가능(사용 허용이면서 인증 유효), 그 외 상태(나머지 전부), 전체를 골라 볼 수 있고, 각 항목에 개수가 표시됩니다. 소유자는 허용된 클라이언트를 비활성화해 이후 호출을 막을 수 있으며 자격 증명 이력은 유지됩니다. 차단된 클라이언트는 다시 활성화하거나 클라이언트 삭제로 지울 수 있습니다. v0.1.2에서는 키가 만료되거나 취소된 뒤에도 클라이언트가 활성으로 보일 수 있었습니다. 업그레이드 후 이런 클라이언트는 그 외 상태에 표시됩니다.

키와 OAuth 승인은 설정 → MCP 접근에서 폐기할 수 있습니다. 만료된 키는 이름 옆에 만료됨이 붙고 지난 키 만료일이 표시됩니다. 새 키를 발급해 앱 설정을 갱신하세요. PAT는 자동 연장되지 않습니다. 만료되었거나 취소된 OAuth 승인 기록을 지우려면 연결 기록 정리의 정리 대상 확인을 누릅니다. 오래된 연결 정리 대화 상자에 지울 기록 수가 표시되며, 정리를 누르면 삭제됩니다. 클라이언트 신원과 호출 이력은 남습니다. 운영자에게 키 문제를 문의할 때는 키 자체가 아니라 키 세부 정보에 표시되는 UUID를 알려 주세요.

접근·인증서 문제가 있으면 개인정보와 안전한 공유, 문제 해결을 참고하세요.

직접 연동 프로그램이나 도구 지침을 작성하려면 API와 MCP 참조를 읽으세요. 워크스페이스 확인, 도구 목록, 안전한 Context 편집, 다음 결과 읽기, 버전별 REST·MCP 명세를 설명합니다.

0.2 작업 대상과 계약

연결 후 list_my_workspaces로 선택 가능한 UUID를 확인하고 guide 및 이후 모든 워크스페이스 도구·동적 프롬프트에 정확한 workspace_id를 전달하세요. 변경한 키의 워크스페이스 권한은 기존 세션의 다음 요청부터 적용됩니다. 계약 개정은 29이며 API·MCP 변경을 확인하고 도구 목록을 다시 받습니다. 수신함는 키 만료 알림도 제공합니다.

키 권한별 도구

화면 권한	예시	제한
읽기(Read)	`guide`, `search`, `fetch`, `read`, `get_index`, `read_agent_page`	읽을 수 있는 문서만 반환합니다. `list_changes`, `list_requested_changes` 권한은 포함하지 않습니다.
쓰기(Write)	Context 생성·편집·참고문헌 `cite`·검토 제출, 허용된 변경·검토 조회	편집자·소유자 역할과 상태 검사를 계속 따릅니다. MCP에 승인 도구는 없습니다.
AI 실행(Run AI)	`build_agent_input_bundle`, `write_agent_page_draft`	Context 쓰기를 대신하지 않습니다. 필요한 읽기 권한도 함께 확인합니다.

토큰의 내부 권한 이름은 mcp:read·mcp:write·mcp:agent이며 화면의 선택과 구분해 진단하세요. 서버 관리자 권한도 워크스페이스 멤버십을 대체하지 않습니다.

클라이언트 플러그인과 스킬

제품 소스의 integrations/claude-plugin, integrations/codex-plugin, integrations/agent-skills에는 검색·규칙·작성과 검토·유지보수를 돕는 지침이 있습니다. MCP 연결을 먼저 구성하고 사용하는 클라이언트의 플러그인·스킬 설치 방식으로 필요한 묶음을 추가하세요. 플러그인은 계정 권한을 늘리지 않습니다. 사용한 도구의 결과와 실제 검토·게시 상태를 계속 확인하세요.

Sources: tool scopes, permission expansion, bundled integrations.

버전 근거: 클라이언트 연결 안내, 클라이언트 검증 범위, 도우미 CLI, HTTP 주소 규칙, 연결 진단, MCP 접근 설정 화면, 워크스페이스 선택, 자격 증명 상태, 키·워크스페이스 한도.

연결 전 준비​

방법 A: OAuth로 브라우저 승인​

방법 B: 액세스 키 만들기​

앱별 직접 등록 예시​

Windows와 설정 위치​

VS Code 확장 연결​

Codex 확장​

Claude Code 확장​

선택 사항: dtxWiki 설정 도우미​

일반 HTTP: 이 컴퓨터 또는 신뢰하는 LAN​

권한을 늘리기 전에 실제 연결 검사​

설정에서 연결 상태 확인​

0.2 작업 대상과 계약​

키 권한별 도구​

클라이언트 플러그인과 스킬​