Claude.ai·Desktop 커스텀 커넥터, 로컬 서버 설정 파일, Claude Code의 claude mcp add로 MCP 서버를 추가하세요.

요약: Claude에 MCP 서버를 추가하는 방법은 세 가지이며, 어느 것을 쓸지는 Claude가 어디에서 실행되는지에 따라 달라집니다. Claude.ai와 Claude Desktop에서는 원격 서버가 커스텀 커넥터입니다. Settings → Connectors에서 URL을 붙여넣고, 요청이 오면 로그인하세요. Claude Desktop에서 로컬 서버(내 컴퓨터에서 실행되는 프로그램)는 claude_desktop_config.json에 넣습니다. Claude Code에서는 모든 것이 claude mcp add 명령 하나로 처리됩니다. 이 가이드는 UnifAPI MCP 서버(https://mcp.unifapi.com)를 예시로 세 가지 방법을 모두 따라가 본 뒤, 도구가 실제로 로드되는지 확인하는 방법을 보여줍니다.

"Claude MCP"는 검색어 하나지만, 설정을 서로 다른 곳에 저장하는 네 가지 표면을 아우릅니다. Claude.ai 웹과 모바일 앱, Claude Desktop 앱, 터미널의 Claude Code, 그리고 VS Code나 JetBrains 안의 Claude Code입니다. 추가하는 서버는 같지만 단계는 다릅니다. 먼저 자신에게 맞는 행을 고르세요.

어느 Claude에 추가하나요?

Claude가 실행되는 곳	서버 추가 방법	지원 범위
Claude.ai (웹, iOS, Android)	Settings → Connectors → Add custom connector	원격 서버(URL), OAuth 로그인
Claude Desktop (macOS, Windows)	원격 서버는 같은 Connectors 화면, 로컬 서버는 `claude_desktop_config.json`	원격(URL)과 로컬(Claude가 실행하는 명령)
Claude Code (터미널)	`claude mcp add …`, 또는 프로젝트용 `.mcp.json` 편집	원격 HTTP, SSE, 로컬 stdio 서버. OAuth는 `/mcp`로
VS Code / JetBrains의 Claude Code	채팅 패널에 `/mcp` 입력, 또는 통합 터미널에서 `claude mcp add` 실행	터미널과 같은 설정

모든 클라이언트의 문서에서 만나게 될 용어 두 가지:

원격 서버는 URL(https://…)입니다. 벤더가 호스팅하며, 브라우저에서 OAuth로 또는 베어러 토큰으로 인증합니다. 내 컴퓨터에서는 아무것도 실행되지 않습니다.
로컬 서버("stdio"라고도 합니다)는 Claude가 대신 시작해 주는 프로그램으로, 보통 npx나 uvx로 실행됩니다. 내 컴퓨터에서 실행되며 표준 입출력으로 Claude와 통신합니다.

UnifAPI는 원격 서버이므로 Claude.ai와 Claude Desktop에서는 커넥터 경로를 사용하면 됩니다. 아래의 claude_desktop_config.json 섹션은 로컬 서버를 위한 것입니다. "claude mcp" 질문의 나머지 절반은 커넥터 화면이 답해 주지 않기 때문입니다.

Claude.ai와 Claude Desktop: 커스텀 커넥터 추가

커스텀 커넥터는 Claude 앱에 원격 MCP 서버를 추가하는 공식 지원 방법입니다. 한 번 연결하면 같은 커넥터를 웹 앱, 모바일 앱, Claude Desktop에서 모두 사용할 수 있습니다.

가장 빠른 방법: 원클릭으로 UnifAPI를 Claude에 추가하세요. 이 링크는 이름과 URL이 미리 채워진 Add custom connector를 열어 주므로 1~3단계를 건너뛸 수 있습니다. 값을 확인하고 Add를 클릭한 다음 4단계부터 계속하세요.

Settings → Connectors를 엽니다(웹에서는 이니셜 → Settings → Connectors, Claude Desktop에서는 Settings → Connectors).
맨 아래로 스크롤해 Add custom connector를 선택합니다.
도구 목록에서 알아볼 수 있는 이름(예: UnifAPI)을 입력하고 서버 URL https://mcp.unifapi.com을 붙여넣습니다.
Add를 클릭한 뒤 Connect를 클릭합니다. Claude가 브라우저에서 서버의 OAuth 로그인을 엽니다. UnifAPI 계정으로 로그인하거나 새로 만들고, 읽기 전용 스코프를 승인하세요.
Claude로 돌아와 커넥터 설정을 열어 모델이 사용할 수 있는 도구를 켜거나 끈 다음, 새 채팅을 시작하세요. 이제 커넥터가 도구 메뉴(메시지 입력창 아래의 슬라이더 아이콘)에 표시됩니다.

자주 걸리는 부분 몇 가지:

커스텀 커넥터는 유료 플랜 기능입니다. Team과 Enterprise 플랜에서는 멤버에게 Add custom connector가 보이기 전에 소유자가 기능을 활성화하거나 조직 전체에 커넥터를 추가해야 할 수 있습니다.
원격 커넥터는 Anthropic의 클라우드를 통해 중개되므로, 서버가 공개 인터넷에서 도달 가능해야 합니다. https://mcp.unifapi.com은 가능하지만 localhost에서 실행되는 서버는 그렇지 않으며, 그래서 로컬 서버는 대신 설정 파일을 사용합니다.
커넥터가 계속 로그인을 요구하면 제거하고 다시 추가하세요. 토큰은 커넥터별로 저장되며, 오래된 토큰은 디버깅하는 것보다 교체하는 쪽이 빠릅니다.

Claude Desktop: claude_desktop_config.json의 로컬 서버

Claude Desktop은 내 컴퓨터에서 MCP 서버를 실행할 수도 있습니다. 이런 서버는 Connectors를 거치지 않고, Claude가 시작할 때 읽는 JSON 파일에 선언합니다.

파일 위치:

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

Settings → Developer → Edit Config를 선택하면 올바른 파일이 열리고, 파일이 없으면 새로 만들어 줍니다. mcpServers 아래의 각 항목은 Claude가 실행하는 명령입니다. MCP 프로젝트의 레퍼런스 filesystem 서버는 다음과 같습니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Desktop"]
    }
  }
}

파일을 저장하고 Claude Desktop을 완전히 종료한 뒤 다시 여세요(macOS에서는 창을 닫는 것만으로는 충분하지 않습니다). 새 채팅의 도구 아이콘 아래에 서버의 도구가 나타납니다. 아무것도 보이지 않으면, 흔한 원인은 Claude Desktop이 보는 PATH에 npx가 없거나 JSON에 후행 쉼표가 있는 경우입니다. 앱의 Developer 설정에는 서버의 시작 출력을 보여주는 로그 뷰어가 있습니다.

이 파일에 원격 URL을 직접 넣을 수는 없습니다. 이 설정은 프로세스를 실행하는 용도입니다. 원격 서버가 커넥터 경로를 제공하지 않는다면 mcp-remote 같은 브리지를 command로 쓸 수 있지만, UnifAPI 같은 서버라면 Connectors 화면이 더 간단하고 OAuth도 원래 있어야 할 브라우저에서 처리됩니다.

Claude Code: claude mcp add

Claude Code는 MCP 서버를 스코프별로 저장하며, 명령은 원격 서버와 로컬 서버에 동일합니다.

HTTP로 UnifAPI 서버를 추가합니다.

claude mcp add --transport http unifapi https://mcp.unifapi.com

기본값은 local 스코프로, 현재 프로젝트에서 나에게만 적용됩니다. 다른 두 스코프도 있습니다.

# Available to you in every project
claude mcp add --transport http --scope user unifapi https://mcp.unifapi.com

# Shared with everyone who clones the repo, written to .mcp.json in the project root
claude mcp add --transport http --scope project unifapi https://mcp.unifapi.com

프로젝트 스코프는 커밋할 수 있는 .mcp.json을 작성합니다.

{
  "mcpServers": {
    "unifapi": {
      "type": "http",
      "url": "https://mcp.unifapi.com"
    }
  }
}

Claude Code는 프로젝트 스코프 서버를 처음 사용하기 전에 승인을 요청하므로, 저장소를 클론한 팀원이 자신이 추가하지 않은 도구에 당황할 일은 없습니다.

그런 다음 Claude Code 안에서 /mcp를 입력하세요. 대화 상자에 설정된 모든 서버와 상태가 나열됩니다. UnifAPI처럼 OAuth를 쓰는 서버에는 Authenticate가 제공되며, 브라우저에서 로그인을 열고, 토큰이 저장되면 Connected를 표시합니다. 같은 /mcp 대화 상자는 VS Code 확장에서도 동작하며, 거기서는 서버 추가와 제거도 할 수 있습니다.

함께 쓰면 유용한 명령:

claude mcp list              # every server and whether it connects
claude mcp get unifapi       # one server's configuration
claude mcp remove unifapi    # remove it from whichever scope holds it

로컬 stdio 서버는 -- 뒤에 명령을 받고, 정적 토큰이 필요한 원격 서버는 --header를 받습니다.

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Projects
claude mcp add --transport http example https://mcp.example.com --header "Authorization: Bearer $EXAMPLE_TOKEN"

UnifAPI도 베어러 토큰(워크스페이스 API 키)을 받지만, OAuth를 권장합니다. 설정 파일에 붙여넣을 키가 없고, 토큰은 읽기 전용 스코프로 제한됩니다.

도구가 실제로 로드되는지 확인

서버를 추가하는 것과 모델이 그것을 사용하는 것은 다른 일입니다. 첫 실제 작업 전에:

Claude.ai나 Desktop에서는 메시지 입력창 아래의 도구 메뉴를 여세요. 커넥터가 도구가 활성화된 상태로 나열되어야 합니다. UnifAPI라면 list_operations, get_operation, call_api 세 가지가 보입니다.
Claude Code에서는 /mcp가 Connected를 표시해야 하고, 도구 목록에 서버의 도구가 mcp__unifapi__ 접두사로 나타납니다.
도구로만 답할 수 있는 질문을 하고 tool-use 블록이 나오는지 지켜보세요. UnifAPI라면 "Reddit용 UnifAPI 작업을 나열해 줘." Claude가 도구를 호출하지 않고 기억에서 답하면 "UnifAPI MCP 도구를 사용해"라고 한 번 말하세요. 그 뒤로는 스스로 도구를 찾는 경향이 있습니다.

UnifAPI 서버에서의 첫 작업

UnifAPI는 X, Instagram, TikTok, YouTube, Reddit, LinkedIn, Threads와 SEO 스택의 실시간 공개 데이터를 하나의 카탈로그로 제공합니다. 엔드포인트마다 도구 하나를 두는 대신, 서버는 Claude에 세 가지 도구를 제공합니다. 작업을 발견하고, 스키마를 검사하고, 호출하는 것입니다. 범위가 제한된 첫 프롬프트:

UnifAPI MCP 도구를 사용해 X에서 "Claude MCP"에 관한 최근 공개 게시물 20개를 찾고, 반복되는 질문을 각각 예시 게시물 하나와 함께 다섯 개의 불릿으로 요약해 줘.

비용: UnifAPI는 반환된 공개 데이터 record당 워크스페이스 크레딧으로 과금합니다(개당 $0.001, 대부분의 record는 1크레딧이며, 최소 크레딧이 더 높은 작업은 카탈로그에 게시됩니다). 모델 토큰은 UnifAPI가 아니라 Claude 플랜에서 소비됩니다. 새 워크스페이스는 첫 충전 전까지 크레딧이 없으며, 첫 충전에는 일회성 보너스가 따라옵니다. 한 번 실행이 최대 수백 크레딧에 머물도록 첫 프롬프트는 범위를 제한하세요("상위 20개", "최근 7일").

엔드포인트가 아니라 작업에서 시작하고 싶다면, 플랫폼 에이전트가 같은 도구를 준비된 프롬프트로 감싸 줍니다. X, LinkedIn, Reddit, TikTok, YouTube, Instagram, Threads에 각각 하나씩 있고, SEO 에이전트는 순위 추적과 AI 가시성을 다룹니다.

문제 해결

증상	위치	해야 할 일
Add custom connector 버튼이 없음	Claude.ai / Desktop	플랜이나 조직에서 아직 커스텀 커넥터를 허용하지 않음. 소유자가 중앙에서 활성화하거나 추가할 수 있음
커넥터는 추가했는데 도구 메뉴에 도구가 없음	Claude.ai / Desktop	커넥터 설정을 열어 도구를 활성화한 뒤 새 채팅 시작
OAuth 창이 끝나지 않음	모두	팝업이 차단되었거나, 워크스페이스를 소유한 계정과 다른 계정으로 로그인함. 제거 후 다시 추가
JSON 파일 편집 후 서버가 보이지 않음	Claude Desktop	JSON 검증(후행 쉼표 없음), 명령이 PATH에 있는지 확인, 앱 완전 종료 후 재실행
`/mcp`가 Failed를 표시	Claude Code	`claude mcp get <name>`으로 URL과 transport 확인. OAuth 서버는 `/mcp` 대화 상자에서 Authenticate 선택
도구는 로드되는데 Claude가 사용하지 않음	모두	프롬프트에서 서버 이름을 한 번 언급. UnifAPI라면 먼저 `list_operations`를 호출하도록 요청
UnifAPI 호출이 `insufficient_credits`를 반환	모두	워크스페이스에 아직 크레딧이 없음. 콘솔에서 한 번 충전한 뒤 같은 프롬프트 재시도

확인한 출처

2026년 10월 14일에 Anthropic 헬프센터의 Claude.ai에 MCP 서버 연결하기 문서, Claude Code MCP 레퍼런스, Model Context Protocol의 Claude Desktop 퀵스타트에 맞춰 작성했습니다. 메뉴는 바뀝니다. 이 글의 단계가 실제 화면과 다르면 위 세 페이지가 기준입니다.

다음에 읽을 글

MCP 설정 - 모든 클라이언트의 현행 호스팅 커넥터 안내를 한곳에 모아둡니다.

Codex MCP 설정 - OpenAI의 Codex CLI와 IDE 확장에서 같은 서버를 설정합니다.

Cursor MCP 설정 - Cursor의 mcp.json, 원클릭 설치 링크, OAuth.

UnifAPI MCP를 범용 및 코딩 에이전트에 연결하기 - ChatGPT, VS Code, OpenClaw, Hermes까지 다루는 더 넓은 온보딩 글.