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)**는 자격 증명이 사용할 도구 종류를 제한합니다. 워크스페이스 멤버십·역할도 함께 검사합니다. 읽기 키는 쓰기를 허용하지 않으며, 뷰어가 강한 키를 요청해도 편집자 권한을 얻지는 않습니다.

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

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

1. 설정 → MCP 접근에서 OAuth 사용 가능 여부를 확인합니다.
2. 화면에 표시된 AI 클라이언트 연결 명령을 선택하거나 해당 앱에서 dtxWiki HTTPS MCP 주소를 추가합니다.
3. 앱의 로그인 안내를 따릅니다. 브라우저 동의 화면에서 계정·허용 워크스페이스·권한 범위를 확인한 뒤 승인합니다.
4. 앱으로 돌아와 아래 실제 읽기 검사를 진행합니다.
5. OAuth 앱에 연결이 표시되는지 확인합니다. 이후 워크스페이스 편집으로 접근 범위를 바꾸거나 승인 취소로 연결 승인을 제거합니다.

이 소스가 확인한 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

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

방법 B: 액세스 키 만들기

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

1. 설정 → MCP 접근의 액세스 키 설정을 엽니다.
2. 클라이언트를 선택하고 “연구 노트북”처럼 알아보기 쉬운 이름을 정합니다.
3. 허용할 워크스페이스를 하나 이상 선택하고 권한 범위를 검토합니다. 지식 검색은 mcp:read부터 시작합니다. 쓰기에는 해당 추가 scope와 편집자·소유자 멤버십이 필요합니다.
4. 만료를 선택합니다. 웹 발급 기본값은 90일이며 30·90·180·365일 또는 무기한을 선택할 수 있습니다.
5. 키를 생성하고 한 번 표시될 때 복사한 뒤 앱 설정을 따릅니다. 공개 저장소·이슈·화면 캡처에 키를 남기지 마세요.

키의 허용 워크스페이스는 현재 화면의 공간만이 아닌 계정 전체에서 선택합니다. 나중에 목록을 바꿔도 앱을 다시 등록할 필요는 없습니다. 계정이 멤버인 것만으로는 충분하지 않습니다. 자격 증명에 없는 공간을 요청하면 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
export DTXWIKI_MCP_PAT
codex mcp add dtxwiki --url https://wiki.example.com/mcp \
  --bearer-token-env-var DTXWIKI_MCP_PAT

앱을 실행할 때도 같은 환경 변수가 필요합니다. 승인된 비밀 저장 도구가 제공할 수 있다면 shell 설정에 키를 직접 쓰는 대신 그 도구를 사용하세요.

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의 역슬래시와 같지 않습니다. 환경 변수를 사용하는 앱은 $env: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 패키지가 필요하지 않습니다.

선택 사항: 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를 권장합니다.

동일 컴퓨터의 로컬 체험에서만 명시적인 로컬 HTTP 허용 옵션을 사용할 수 있습니다.

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

이 주소는 dtxWiki가 실행 중인 컴퓨터에서만 사용할 수 있습니다. 원격 앱은 접근 가능한 서버의 HTTPS 주소가 필요합니다.

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

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

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

브라우저에서 읽을 수 있는 공간과 내용이 맞는지 확인합니다. 나중에 쓰기를 허용한다면 연습 공간에서 이름을 명확히 정한 초안을 만들어 보고 브라우저에서 편집·검토 상태를 확인하세요. 등록 항목·연결 표시·서버 doctor 성공만으로 실제 읽기나 안전한 편집을 증명하지는 않습니다.

키와 OAuth 승인은 설정 → MCP 접근에서 폐기할 수 있습니다. 키가 만료되면 새로 발급하고 앱 설정을 갱신합니다. PAT는 자동 연장되지 않습니다. 접근·인증서 문제가 있으면 개인정보와 안전한 공유, 문제 해결을 참고하세요.

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

---

버전 근거: 클라이언트 연결 안내, 클라이언트 검증 범위, 도우미 CLI.