사용 가이드

thumbnail

MCP

사용 중인 AI 도구가 Soha AI 대시보드 데이터를 직접 조회할 수 있도록 연결해 보세요.

MCP란?

MCP는 사용 중인 AI 도구와 Soha AI를 연결하는 방식이에요. 연결하면 Soha AI 데이터를 바탕으로 질문하고, 선택한 기능을 사용할 수 있어요.

예를 들어 “최근 AI 답변에서 우리 브랜드가 얼마나 언급됐는지 알려줘”라고 질문할 수 있어요.

먼저 Soha AI 대시보드 오른쪽 위에서 연결을 눌러 사용할 AI 도구를 선택해 주세요. 필요한 기능을 고른 뒤, 데이터를 변경하는 도구를 사용하지 않으려면 읽기 전용을 켜 주세요. 아래에서 해당 도구의 안내를 따라 연결할 수 있어요.

위 이미지는 Claude Code를 선택한 예시예요. 사용할 도구와 기능, 읽기 전용 여부는 필요에 맞게 선택해 주세요.

  • Claude Code: 터미널에서 사용하는 Claude 도구

  • Claude Desktop: 컴퓨터에 설치해서 사용하는 Claude 앱

  • Codex CLI: 터미널에서 사용하는 Codex 도구

터미널은 명령을 입력해 컴퓨터 작업을 실행하는 창이에요. 사용하려는 도구의 안내를 따라 해 주세요. 여러 도구를 사용한다면 각각 연결할 수 있어요.

연결 전 준비: Node.js 확인하기

Claude Desktop과 Codex CLI를 아래 방법으로 연결하려면 Node.js가 필요해요. 연결을 돕는 프로그램이라 직접 프로그래밍할 필요는 없어요.

  1. 터미널을 열어 주세요.

    1. Mac은 Command + Space를 누르고 “터미널”을 검색해 주세요.

    2. Windows는 시작 메뉴에서 “PowerShell”을 검색해 열어 주세요.

    3. WSL(Windows에서 Linux를 사용하는 환경)에서 Codex를 실행한다면 해당 WSL 터미널을 열어 주세요.

  2. node -v를 입력하고 Enter를 누른 다음, npx -v도 입력하고 Enter를 눌러 주세요. 두 명령에서 버전 숫자가 보이고 Node.js 버전이 18 이상이면 준비된 상태예요.

  3. 명령을 찾을 수 없거나 버전이 낮다면 Node.js 공식 다운로드 페이지에서 컴퓨터에 맞는 LTS 설치 파일을 받아 설치해 주세요. WSL을 사용한다면 공식 페이지의 Linux 설치 안내를 따라 WSL 안에 설치해 주세요. 설치가 끝나면 사용 중인 터미널을 닫았다가 다시 열고 두 명령을 확인해 주세요.

주요 AI 모델 연결하는 방법

아래 설정은 기능 그룹을 모두 선택했을 때의 예시예요. 필요한 기능과 읽기 전용 여부를 고른 뒤 Soha AI의 MCP 연결 창에서 생성된 설정값을 사용해 주세요.

1. Claude Code

  1. MCP 서버 추가

    1. Claude Code가 설치된 컴퓨터에서 터미널을 열어 주세요.

      1. Mac은 Command + Space를 누르고 “터미널”을 검색하세요.

      2. Windows는 시작 메뉴에서 “PowerShell”을 검색해 주세요.

    2. 연결해서 사용할 작업 폴더로 이동해 주세요.

      1. Mac에서는 터미널에 cd와 한 칸을 입력한 뒤 Finder의 폴더를 터미널로 끌어와 Enter를 누르면 돼요.

      2. Windows에서는 탐색기의 폴더 주소를 복사하고 PowerShell에 cd "폴더 주소"를 입력하고 Enter를 눌러 주세요.

    3. Soha AI의 연결 창에서 Claude Code와 필요한 기능을 선택하고, MCP 서버 추가 명령 옆의 복사 버튼을 눌러 주세요.

    4. 복사한 명령을 터미널에 붙여넣고 Enter를 눌러 주세요. 아래는 모든 기능을 선택했을 때의 예시예요. 이 명령은 현재 작업 중인 프로젝트에 설정을 저장해요. 프로젝트 설정 파일을 다른 사람과 공유하면 연결 설정도 함께 공유될 수 있어요.

Plaintext
claude mcp add --scope project --transport http soha-ai "https://www.soha-ai.com/api/mcp?features=account%2Cinsights%2Csites%2Cprompts%2Canalysis%2Ckeywords%2Ccontent%2Cagents"

  1. 인증하기

    1. 터미널에서 claude를 입력하고 Enter를 눌러 Claude Code를 시작해 주세요. 프로젝트의 서버 사용을 승인하라는 안내가 나오면 soha-ai를 확인하고 승인해 주세요.

    2. Claude Code가 열린 뒤 입력창에 아래 /mcp를 입력하고 Enter를 눌러 주세요.

    3. 목록에서 soha-ai를 선택하고 Authenticate를 눌러 주세요.

    4. 브라우저가 열리면 Soha AI 계정으로 로그인하고 연결을 승인해 주세요. 브라우저가 자동으로 열리지 않으면 터미널에 표시된 주소를 복사해 브라우저에서 열어 보세요.

Plaintext
/mcp

  1. 연결 확인

    1. Claude Code에서 /mcp를 열어 soha-ai의 연결 상태와 도구 목록을 확인해 주세요. soha_로 시작하는 도구가 보이면 연결된 상태예요.

    2. 연결을 관리하거나 해제하려면 Soha AI 대시보드 왼쪽 아래의 사용자 프로필 → 설정 → MCP 연결을 열어 주세요.

2. Claude Desktop

준비물: 컴퓨터에 설치한 Claude Desktop 앱과 Node.js가 필요해요. 위의 “연결 전 준비: Node.js 확인하기”를 먼저 따라 해 주세요. 이 연결 방식은 mcp-remote라는 도우미 프로그램을 사용해요.

  1. 설정 파일 열고 연결 정보 추가하기

    1. Claude Desktop 앱을 열고 설정 → 개발자 → 설정 파일 편집을 선택해 주세요.

    2. 열린 폴더에서 claude_desktop_config.json 파일을 찾아 일반 텍스트 편집기로 열어 주세요. 파일을 바꾸기 전에 복사본을 만들어 두면 원래 파일을 보관할 수 있어요.

    3. Soha AI 연결 창에서 Claude Desktop과 필요한 기능을 선택한 뒤, 생성된 설정을 복사해 주세요.

    4. 파일이 비어 있거나 내용이 {}뿐이라면 기존 내용을 지우고 복사한 설정 전체를 붙여넣어 주세요. 아래는 모든 기능을 선택했을 때의 예시예요.

      1. 다른 설정이 있다면 파일 전체를 덮어쓰지 마세요. 기존 mcpServers 안에 soha-ai 항목만 추가하고, 다른 항목과 쉼표로 구분해야 해요. 같은 이름의 항목이 이미 있으면 중복해서 추가하지 마세요. mcpServers가 없거나 합치는 방법이 어렵다면 파일을 그대로 두고 Soha AI 고객지원에 문의해 주세요.

    5. 저장한 뒤 Claude Desktop을 완전히 종료했다가 다시 열어 주세요.

Plaintext
{
  "mcpServers": {
    "soha-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.soha-ai.com/api/mcp?features=account%2Cinsights%2Csites%2Cprompts%2Canalysis%2Ckeywords%2Ccontent%2Cagents"
      ]
    }
  }
}

  1. 인증하기

    1. Claude Desktop을 다시 연 뒤 브라우저에 로그인 안내가 나타나면 Soha AI 계정으로 로그인하고 연결을 승인해 주세요.

    2. 앱에서 soha-ai와 연결 버튼이 보이면 연결을 선택해 주세요. 화면 구성에 따라 대화창의 + → 커넥터 또는 설정 → 개발자에서 서버와 상태를 확인할 수 있어요.브라우저 안내나 서버가 나타나지 않으면 Node.js 설치 여부와 설정 파일을 확인하고, 해결되지 않으면 Soha AI 고객지원에 문의해 주세요.

  2. 연결 확인

    1. Claude Desktop의 도구 목록에 soha_로 시작하는 도구가 보이는지 확인해 주세요.연결을 관리하거나 해제하려면 Soha AI 대시보드 왼쪽 아래의 사용자 프로필 → 설정 → MCP 연결을 열어 주세요.

3. Codex CLI

준비물: Codex CLI와 Node.js가 필요해요. 위의 “연결 전 준비: Node.js 확인하기”를 먼저 따라 해 주세요. 아래 방법은 mcp-remote라는 도우미 프로그램을 사용해요.

  1. 설정 파일 찾고 연결 정보 추가하기

    1. 설정 폴더를 열어 주세요.

      1. Mac은 Finder 상단 메뉴의 이동 → 폴더로 이동을 선택하고 ~/.codex를 입력해 주세요.

      2. Windows에서 PowerShell로 Codex를 쓰는 경우 파일 탐색기의 주소창에 %USERPROFILE%\.codex를 입력해 주세요.

      3. Windows의 WSL에서 Codex를 쓰는 경우에는 WSL 터미널에서 cd ~/.codex를 입력하고 Enter를 누른 뒤 explorer.exe . 명령을 입력하면 해당 폴더를 열 수 있어요.

    2. config.toml을 일반 텍스트 편집기로 열고, 변경 전에 복사본을 만들어 두면 좋아요. 파일이 없다면 새 일반 텍스트 파일을 만들어 이 폴더에 config.toml이라는 이름으로 저장해 주세요. 확장자가 .toml.txt가 되지 않도록 확인해 주세요.

      1. Mac의 텍스트 편집기는 서식 → 일반 텍스트 만들기를 선택하고, Windows 메모장은 저장할 때 파일 형식을 모든 파일로 선택해 주세요.

      2. 폴더 자체가 보이지 않으면 Codex CLI를 먼저 실행한 뒤 다시 확인하고, 여전히 없다면 Soha AI 고객지원에 문의해 주세요.

    3. Soha AI 연결 창에서 Codex CLI와 필요한 기능을 선택하고 생성된 설정을 복사해 주세요.

    4. 파일의 기존 내용을 지우지 말고, 같은 [mcp_servers.soha_ai] 항목이 없다면 맨 아래에 한 줄을 띄운 뒤 붙여넣어 주세요. 같은 항목이 이미 있다면 중복해서 추가하지 말고 기존 설정을 확인해 주세요.

    5. 파일을 저장하고 Codex를 완전히 종료했다가 다시 열어 주세요. 아래는 모든 기능을 선택한 예시예요.

Plaintext
[mcp_servers.soha_ai]
command = "npx"
args = ["-y", "mcp-remote", "https://www.soha-ai.com/api/mcp?features=account%2Cinsights%2Csites%2Cprompts%2Canalysis%2Ckeywords%2Ccontent%2Cagents"]

  1. 인증하기

    1. Codex를 다시 시작한 뒤 브라우저에 로그인 안내가 나타나면 Soha AI 계정으로 로그인하고 연결을 승인해 주세요.

    2. 브라우저 안내가 나타나지 않고 연결도 되지 않으면 Node.js와 설정 파일을 다시 확인해 주세요. 그래도 해결되지 않으면 Soha AI 고객지원에 문의해 주세요.

  2. 연결 확인

    1. Codex를 실행한 화면의 입력창에 /mcp를 입력해 soha_ai의 연결 상태와 도구를 확인해 주세요. soha_로 시작하는 도구가 보이면 연결된 상태예요.

    2. 연결을 관리하거나 해제하려면 Soha AI 대시보드 왼쪽 아래의 사용자 프로필 → 설정 → MCP 연결을 열어 주세요.

연결이 되지 않을 때

  • Soha AI 연결 창에서 사용 중인 도구를 선택하고 생성된 설정을 복사했는지 확인해 주세요.

  • 설정 파일을 변경했다면 앱을 완전히 종료한 뒤 다시 실행해 주세요. Claude Code는 연결 명령을 실행한 프로젝트 폴더에서 다시 확인해 주세요.

  • 계속 문제가 생기면 사용 중인 도구, 컴퓨터 종류와 오류가 발생한 단계를 Soha AI 고객지원에 알려 주세요. 비밀번호, 인증 코드와 토큰은 보내지 마세요.

자주 묻는 질문

MCP를 연결하면 무엇을 할 수 있나요?

Soha AI MCP를 연결하면 사용 중인 AI 도구에서 Soha AI 데이터를 바탕으로 질문하고 선택한 기능을 활용할 수 있어요. Claude Code, Claude Desktop, Codex CLI에서도 연결할 수 있어요. 연결할 때 필요한 기능 그룹과 읽기 전용 여부를 선택해 주세요.

Claude Desktop과 Codex CLI를 쓰려면 Node.js가 필요한가요?

Claude Desktop과 Codex CLI를 mcp-remote 방식으로 연결할 때는 Node.js와 npx가 필요해요. 터미널에서 node -v와 npx -v를 입력해 버전이 표시되는지 확인해 주세요. Node.js 버전이 18보다 낮거나 명령을 찾지 못한다면 공식 다운로드 페이지에서 LTS 버전을 설치한 뒤 터미널을 다시 열어 확인해 주세요. WSL에서 사용한다면 WSL 안에 설치해 주세요.

이미 MCP 설정이 있는데 파일을 덮어써도 되나요?

기존 설정이 있다면 먼저 파일을 복사해 보관하고, 전체를 덮어쓰지 마세요. Claude Desktop은 기존 mcpServers 안에 soha-ai 항목을 추가하고 다른 항목과 쉼표로 구분해요. Codex CLI는 같은 [mcp_servers.soha_ai] 항목이 없을 때만 파일 맨 아래에 추가해 주세요. 같은 이름이 이미 있으면 중복하지 마세요. Claude Desktop에 mcpServers가 없거나 합치기 어렵다면 파일을 그대로 두고 고객지원에 문의해 주세요.

브라우저에 Soha AI 로그인 창이 열리지 않을 때는 어떻게 하나요?

Claude Code는 실행 중인 입력창에 /mcp를 입력하고 soha-ai → Authenticate를 선택해 주세요. 브라우저가 열리지 않으면 터미널에 표시된 주소를 복사해 직접 열어 보세요. Claude Desktop이나 Codex CLI는 프로그램을 완전히 종료했다가 다시 열고 Node.js와 설정 파일을 확인해 주세요. 계속 연결되지 않으면 고객지원에 문의해 주세요.

MCP가 제대로 연결됐는지 어떻게 확인하나요?

Claude Code에서는 입력창에 /mcp를 입력해 soha-ai의 연결 상태를 확인해 주세요. Codex CLI에서는 /mcp를 입력해 soha_ai의 상태와 도구를 확인할 수 있어요. Claude Desktop에서는 도구 목록을 확인해 주세요. 각 도구에서 soha_로 시작하는 도구가 보이면 연결된 상태예요.

MCP 연결을 해제하거나 관리하려면 어떻게 하나요?

Soha AI 대시보드 왼쪽 아래에서 사용자 프로필 → 설정 → MCP 연결을 열어 주세요. 이 화면에서 연결을 확인하고 관리하거나 해제할 수 있어요.

연결이 안 될 때 고객지원에 무엇을 알려야 하나요?

사용 중인 도구(Claude Code, Claude Desktop 또는 Codex CLI), 운영체제(Mac·Windows 등)와 오류가 발생한 단계를 알려 주세요. Windows에서 WSL을 사용한다면 그 사실도 함께 알려 주세요. 오류 메시지를 전달할 때는 비밀번호, 인증 코드, 토큰 등 민감한 정보를 먼저 지워 주세요.