Claude Desktop 연결

개인용 MCP host 의 대표 격이 Claude Desktop 이야. JSON 설정 파일 하나를 읽어서 (macOS 는 ~/Library/Application Support/Claude/claude_desktop_config.json, 다른 플랫폼도 비슷해) 시작할 때 띄울 server 목록을 가져와. Server 항목에는 실행 명령과 인자, 그리고 필요하면 환경 변수를 적어.

끝에서 끝까지의 흐름은 이래. Server 를 짜고, 설정에 항목을 추가하고, Claude Desktop 을 다시 띄우면, 그 server 의 tool 이 모델의 tool 메뉴에 나타나. 첫 연결이 초반 버그를 거의 다 드러내는 지점이야. 대개는 stdout 이 오염됐거나 (Track 6), 띄우는 환경에 의존성이 빠져 있거나 둘 중 하나지.

다른 함정은 환경 변수야. Claude Desktop 은 server 를 거의 텅 빈 환경에서 띄워. $HOME 정도만 잡혀 있고 나머지는 거의 없다고 보면 돼. Server 가 API key 를 써야 한다면 설정의 env 필드로 직접 넘기거나, server 안에서 OS keychain 을 읽어와야 해. Shell 에서 잡아둔 변수에 기대지 마 — 거기엔 없어.

Code

claude_desktop_config.json entry·json

{
  "mcpServers": {
    "my-tools": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "STRIPE_API_KEY": "sk_live_..."
      }
    },
    "github": {
      "command": "uvx",
      "args": ["github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Debug log 위치·bash

# macOS
tail -f ~/Library/Logs/Claude/mcp.log
tail -f ~/Library/Logs/Claude/mcp-server-my-tools.log

# 'mcp-server-my-tools.log' 이 server stderr 캡처 — diagnostic 보내야 할 곳.

Exercise

작은 server 를 claude_desktop_config.json 에 추가하고 Claude 를 다시 띄워. 모델한테 그 tool 을 써보라고 해. 모델이 tool 을 부르는 동안 server 별 log 가 흘러가는 걸 지켜봐. 진짜 모델의 판단을 따라 네 진단 로그가 한 줄씩 찍히는 걸 처음 보는 순간, protocol 이 더는 추상이 아니게 돼.

Code

External links

Exercise

Progress

댓글 0