Claude를 digna에 연결¶

이 가이드는 Claude를 digna MCP Server에 연결하는 방법을 설명합니다. AI 에이전트 개요에 설명된 대로 digna 설치의 MCP 엔드포인트와 API 키가 필요합니다.

예시에서는 엔드포인트로 https://digna.example.com/mcp를 사용합니다. 사용자의 엔드포인트로 바꾸세요.

연결 방법 선택¶

회사 네트워크 내부에서 실행되는 digna 설치에는 Claude Code 또는 로컬 브리지를 사용하는 Claude Desktop을 사용하세요.

Claude Code¶

1. 서버 추가¶

API 키를 환경 변수에 넣은 다음 서버를 추가합니다:

export DIGNA_API_KEY='<api key>'
claude mcp add --transport http --scope user digna https://digna.example.com/mcp --header "Authorization: Bearer $DIGNA_API_KEY"

명령을 실행할 때 셸이 $DIGNA_API_KEY를 채워 넣으므로, Claude Code는 키를 자체 구성에 저장합니다.

--scope는 서버를 사용할 수 있는 범위를 정합니다:

2. 팀과 서버 공유(선택 사항)¶

프로젝트의 모든 사람에게 같은 서버를 제공하려면 프로젝트 루트에 .mcp.json 파일을 추가합니다. 파일에 키를 쓰지 마세요. Claude Code가 각 사용자의 환경에서 ${DIGNA_API_KEY}를 채워 넣습니다:

{
  "mcpServers": {
    "digna": {
      "type": "http",
      "url": "https://digna.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DIGNA_API_KEY}"
      }
    }
  }
}

각 사용자는 DIGNA_API_KEY를 자신의 키로 설정합니다. Claude Code는 이 파일을 처음 발견하면 그 안의 서버를 사용할지 묻습니다.

3. 연결 확인¶

셸에서 다음을 실행합니다:

claude mcp list

digna 서버에 ✔ Connected가 표시되어야 합니다. Claude Code 세션 안에서는 /mcp를 실행하면 서버와 그 도구를 볼 수 있습니다.

로컬 브리지를 사용하는 Claude Desktop¶

Claude Desktop의 구성 파일은 사용자의 컴퓨터에서 로컬 MCP 서버를 시작합니다. 오픈 소스 패키지인 mcp-remote라는 작은 브리지가 그곳에서 실행되며, 모든 요청을 API 키와 함께 digna 엔드포인트로 전달합니다. 브리지가 사용자의 컴퓨터에서 실행되므로 회사 네트워크 내부의 digna와도 작동합니다.

1. Node.js 설치¶

브리지에는 Node.js 18 이상이 필요합니다. Claude Desktop은 시스템에 설치된 Node.js 버전을 사용합니다. 다음 명령으로 확인하세요:

node --version

2. 구성 파일 편집¶

claude_desktop_config.json을 엽니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

digna 서버를 추가합니다. 파일에 이미 mcpServers 섹션이 있다면 그 안에 digna 항목을 추가하세요:

{
  "mcpServers": {
    "digna": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://digna.example.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <api key>"
      }
    }
  }
}

3. Claude Desktop 다시 시작¶

Claude Desktop을 완전히 종료한 다음 다시 시작합니다. 새 채팅에서 +를 클릭하고 Connectors를 엽니다. digna가 목록에 있고 켜져 있어야 합니다.

사용자 지정 커넥터¶

사용자 지정 커넥터를 사용하면 로컬 설정 없이 claude.ai, Claude Desktop, Claude 모바일 앱에서 digna를 사용할 수 있습니다. Anthropic의 클라우드가 엔드포인트에 연결하므로, 다음 조건을 만족할 때만 작동합니다:

• digna 엔드포인트가 인터넷에서 HTTPS로 접근 가능해야 합니다
• Claude 조직의 Add custom connector 대화 상자에 Request headers 옵션이 있어야 합니다. Anthropic은 이 옵션을 일부 조직에만 베타로 제공합니다

1. 커넥터 설정 열기¶

• Free, Pro, Max, Ultra 플랜: Customize > Connectors로 이동하여 Add custom connector를 클릭합니다.
• Team, Enterprise 플랜: Owner가 Organization settings > Connectors로 이동하여 Add를 클릭한 다음 Custom을 클릭하고, 유형을 묻는 경우 Web을 선택합니다.

2. 커넥터 정보 입력¶

1. MCP server URL: https://digna.example.com/mcp
2. Authentication: No sign-in
3. Request headers: 헤더 이름으로 authorization을 선택하고, 값으로 Bearer라는 단어와 공백을 포함하여 Bearer <api key>를 입력한 뒤 Required로 표시합니다.
4. Add를 클릭합니다.

Team 및 Enterprise 플랜에서는 이후 구성원이 Customize > Connectors에서 연결하며, 이 커넥터에는 Custom 레이블이 붙습니다.

Claude에서는 기존 커넥터의 헤더를 변경할 수 없습니다. 새 키를 사용하려면 커넥터를 제거한 뒤 다시 추가하세요.

Claude 문제 해결¶

claude mcp list에 Failed to connect가 표시됨¶

claude mcp get digna를 실행하여 원인을 확인하세요. 401은 키가 거부되었다는 뜻입니다. 401 Unauthorized를 참조하세요. Claude Code는 키를 복사할 때 자주 함께 들어가는 키 앞뒤의 공백이나 줄바꿈에 대해서도 경고합니다.

Claude Desktop에 digna가 표시되지 않음¶

• Node.js 18 이상이 설치되어 있는지 확인하세요: node --version.
• claude_desktop_config.json이 유효한 JSON인지 확인하세요. 쉼표 하나만 빠져도 파일의 모든 서버가 로드되지 않습니다.
• 창만 닫지 말고 Claude Desktop을 완전히 종료한 다음 다시 시작하세요.

사용자 지정 커넥터가 서버에 접근할 수 없음¶

Anthropic의 클라우드가 엔드포인트에 접근할 수 없습니다. 엔드포인트가 유효한 인증서와 함께 인터넷에서 HTTPS로 접근 가능한지 확인하거나, 대신 Claude Code를 통해 연결하세요.

함께 보기¶

• AI 에이전트 개요: 엔드포인트, API 키, 보안 및 일반적인 문제 해결
• Gemini: Antigravity 또는 Gemini CLI 연결
• digna Agentic: AI 에이전트가 digna로 할 수 있는 일