W&B MCP Server 사용하기

IDE 또는 AI 에이전트를 W&B Model Context Protocol (MCP) 서버에 연결하여 자연어로 W&B 데이터와 문서를 쿼리하고 분석하세요.

Model Context Protocol(MCP)은 AI 에이전트가 외부 도구를 호출할 수 있도록 하는 개방형 표준입니다. W&B MCP Server는 IDE, 코딩 도우미 또는 채팅 에이전트가 W&B 데이터와 문서에 직접 액세스할 수 있게 해주므로, 복사해서 붙여넣지 않아도 Runs, 트레이스, evaluations, 아티팩트에 관한 질문에 답할 수 있습니다. 서버로 수행할 수 있는 작업의 전체 목록은 W&B MCP Server 기능 섹션을 참조하세요.

다음을 포함한 대부분의 IDE, 코딩 클라이언트, 채팅 에이전트와 기본적으로 통합됩니다:

• Cursor
• Visual Studio Code (VS Code)
• Claude Code
• Codex
• Gemini CLI
• Mistral LeChat
• Claude Desktop

​

배포 유형

더 높은 격리 수준과 유연성이 필요하다면 Hosted MCP 서버를 사용하거나 로컬 버전을 설정할 수 있습니다. 로컬 버전을 사용하려면 클라이언트에서 서버에 액세스하는 데 다른 URL을 사용해야 합니다.

Hosted 서버(권장)

클라이언트가 W&B API 키를 사용해 HTTP로 연결하는 W&B 관리형 MCP 서버입니다. 설치할 필요가 없고, 유지 관리해야 할 로컬 프로세스도 없습니다.

Hosted 서버 사용

로컬 설치

MCP 서버를 자신의 머신에서 STDIO 또는 HTTP로 실행하세요. 에어갭 환경에서의 오퍼레이션, 특정 릴리스에 고정, 맞춤형 서버 동작, 활발한 서버 개발, 또는 STDIO만 지원하는 클라이언트를 지원해야 할 때 사용합니다.

MCP 서버를 로컬에서 실행

W&B를 Dedicated Cloud 또는 Self-Managed에서 실행 중인데 인스턴스에서 Hosted MCP 서버가 아직 활성화되어 있지 않다면, W&B 지원팀 또는 W&B account team에 문의해 요청하세요.

​

사전 요구 사항

클라이언트를 설정하기 전에 다음을 수행하세요:

• wandb.ai/authorize에서 W&B API 키를 생성하세요.
• 키를 WANDB_API_KEY 환경 변수로 설정하거나 클라이언트에 Bearer 토큰으로 전달하세요.
• 기본 인스턴스가 아닌 다른 인스턴스에 연결하는 Dedicated Cloud, Self-Managed 및 로컬 설치의 경우 WANDB_BASE_URL 환경 변수를 해당 인스턴스 URL로 설정하세요.

​

W&B 호스팅 서버 사용

W&B는 모든 배포 유형에 대해 관리형 MCP 서버를 운영합니다. 별도로 설치할 필요는 없습니다. Authorization 헤더에 W&B API 키를 포함해 HTTP로 연결하도록 클라이언트를 설정하세요.

​

연결 URL

URL은 W&B 배포 유형에 따라 달라집니다.

Deployment	Server URL
Multi-tenant Cloud	https://mcp.withwandb.com/mcp
Dedicated Cloud	https://<your-instance>/mcp
Self-Managed	https://<your-instance>/mcp

Dedicated Cloud 또는 Self-Managed를 사용하는 경우 https://mcp.withwandb.com/mcp를 https://<your-instance>/mcp로 바꾸고, 나머지는 그대로 유지하세요. 아래 클라이언트 설정은 Multi-tenant URL을 사용합니다.

Claude Code

터미널에서 다음 명령어를 실행하되, Bearer 토큰을 W&B API 키로 바꾸세요:

claude mcp add --transport http wandb https://mcp.withwandb.com/mcp \
  --header "Authorization: Bearer <your-wandb-api-key>"

Claude Code를 전역으로 구성하려면 --scope user를 추가하세요. 현재 프로젝트만 구성하려면 이 옵션을 생략하세요.

List my W&B entities.라고 요청해 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하고 사용자 이름과 속한 모든 Teams를 반환해야 합니다. 연결에 실패하면 문제 해결을 참조하세요. 자세한 내용은 Claude Code’s MCP documentation을 참조하세요.

Claude Desktop

Claude Desktop에 기본으로 제공되는 맞춤형 connector 인터페이스는 원격 MCP 서버에 대한 API 키 인증을 지원하지 않습니다. 이를 우회하려면 mcp-remote npm 프록시를 사용해 Claude Desktop을 W&B 원격 MCP 서버에 연결하세요. 이 프록시는 로컬에서 실행되며, Bearer 토큰을 사용해 요청을 https://mcp.withwandb.com/mcp로 전달합니다.

시스템에 Node.js가 설치되어 있어야 합니다.

텍스트 편집기에서 Claude Desktop 설정 파일을 여세요. OS별 설정 파일 위치는 다음과 같습니다.

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

설정 파일의 JSON 객체에 다음 내용을 추가하고, <your-wandb-api-key>를 W&B API 키로 바꾸세요:

{
  "mcpServers": {
    "wandb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.withwandb.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-wandb-api-key>"
      }
    }
  }
}

전체 헤더 값은 일부 Claude Desktop 버전의 공백 이스케이프 문제를 우회하기 위해 args에 직접 설정하지 않고 env 필드를 통해 설정합니다.

새 설정을 적용하려면 Claude Desktop을 다시 시작하세요. List my W&B entities. 라고 입력해 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하고 사용자 이름과 속한 모든 팀을 반환해야 합니다. 연결에 실패하면 문제 해결을 참조하세요.

Codex

W&B API 키를 환경 변수로 내보낸 다음, 다음을 실행하세요:

export WANDB_API_KEY=<your-wandb-api-key>
codex mcp add wandb \
  --url https://mcp.withwandb.com/mcp \
  --bearer-token-env-var WANDB_API_KEY

List my W&B entities.라고 요청해 연결을 확인하세요. 에이전트는 list_entities_tool을 호출하고 사용자 이름과 속한 팀을 반환해야 합니다. 연결에 실패하면 문제 해결을 참조하세요.

Cursor

원클릭 설치 링크를 사용해 Cursor에 서버를 자동으로 설치한 다음, Authorization 필드의 placeholder를 W&B API 키로 바꾸세요.

Cursor를 수동으로 설정하려면 다음 단계를 따르세요.

1. macOS에서는 Cursor > Settings > Cursor Settings를 여세요. Windows 또는 Linux에서는 Preferences > Settings > Cursor Settings를 여세요.

2. Tools and MCP를 선택하세요.

3. Installed MCP Servers에서 Add Custom MCP를 선택하세요. Cursor가 mcp.json 설정 파일을 엽니다.

4. mcpServers 객체에 다음 내용을 추가하세요.

   {
     "mcpServers": {
       "wandb": {
         "transport": "http",
         "url": "https://mcp.withwandb.com/mcp",
         "headers": {
           "Authorization": "Bearer <your-wandb-api-key>",
           "Accept": "application/json, text/event-stream"
         }
       }
     }
   }
   

5. Cursor를 다시 시작하세요.

6. List my W&B entities.라고 입력해 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하고 사용자 이름과 소속된 팀을 반환해야 합니다.

연결에 실패하면 문제 해결을 참조하세요. 자세한 내용은 Cursor의 MCP 문서를 참조하세요.

Gemini CLI

W&B MCP 확장 프로그램을 설치하세요:

gemini extensions install https://github.com/wandb/wandb-mcp-server

Gemini CLI를 다시 시작하세요. List my W&B entities.라고 입력해 연결을 확인하세요. 에이전트는 list_entities_tool을 호출하고 사용자 이름과 속한 모든 팀을 반환해야 합니다.

연결에 실패하면 문제 해결을 참조하세요. 자세한 내용은 Gemini CLI의 MCP 문서를 참조하세요.

Mistral LeChat

1. LeChat에서 Intelligence 메뉴를 열고 Add Connector를 선택하세요.
2. Custom MCP Connector를 선택하세요.
3. 다음 필드를 설정하세요.
   • Connector Server: https://mcp.withwandb.com/mcp
   • Description: (선택 사항) 짧은 설명
   • Authentication Method: API Token Authentication을 선택하세요.
   • Header name: Authorization으로 그대로 두세요.
   • Header type: Bearer를 선택하세요.
   • Header value: W&B API 키
4. Create를 선택하세요.
5. List my W&B entities.라고 입력해 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하고 사용자 이름과 속한 Teams를 반환해야 합니다.

연결에 실패하면 Troubleshooting을 참조하세요. 자세한 내용은 LeChat의 MCP 문서를 참조하세요.

OpenAI Responses API

OpenAI Responses API 호출에서 tools 필드에 서버를 추가하세요:

import os
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "wandb",
        "server_description": "Query W&B data",
        "server_url": "https://mcp.withwandb.com/mcp",
        "authorization": os.getenv("WANDB_API_KEY"),
        "require_approval": "never",
    }],
    input="List my W&B entities.",
)

print(resp.output_text)

W&B API 키 자체를 authorization 값으로 전달하세요. OpenAI는 서버를 호출할 때 Bearer 를 앞에 붙이므로 직접 포함하지 마세요. OpenAI MCP 인테그레이션은 서버 측에서 실행되므로 로컬 MCP 서버에 연결할 수 없습니다. 로컬에서 개발하는 경우 MCP 서버를 로컬에서 실행하기를 참조하세요.

VS Code

전역 또는 워크스페이스 mcp.json(예: ~/.vscode/mcp.json 또는 .vscode/mcp.json)을 열고 다음을 추가하세요:

{
  "servers": {
    "wandb": {
      "type": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-wandb-api-key>"
      }
    }
  }
}

VS Code를 다시 시작하고, MCP 패널에 서버가 표시되는지 확인한 다음, List my W&B entities.를 입력해 연결을 확인하세요. 에이전트는 list_entities_tool을 호출하고 사용자 이름과 속한 Teams를 반환해야 합니다.

연결에 실패하면 문제 해결을 참조하세요.

​

MCP 서버를 로컬에서 실행

로컬 설치는 호스팅 서버의 대안이며, 어떤 배포 유형에서도 기본값은 아닙니다. 호스팅 서버가 현재 설정에 맞지 않을 때 사용하세요.

로컬에서 실행하는 일반적인 이유는 다음과 같습니다.

• 클라이언트가 호스팅된 W&B 엔드포인트에 연결할 수 없는 에어갭 또는 오프라인 환경.
• 버전 고정. 호스팅 서버는 main 브랜치를 따릅니다. 로컬 설치는 특정 릴리스 태그에 고정할 수 있습니다.
• 도구 설명 변경, 도구 추가, 기본값이 아닌 응답 token 예산 설정과 같은 맞춤형 서버 동작.
• 서버 자체를 활발히 개발 중인 경우.
• STDIO 전용 클라이언트 또는 로컬 프로세스가 필요한 클라이언트.

Dedicated Cloud 또는 Self-Managed 사용자의 경우 호스팅 방식이 권장됩니다. 인스턴스에서 호스팅 서버가 아직 활성화되지 않았거나 위 이유 중 하나에 해당하는 경우에만 wandb/wandb-mcp-server 의 로컬 설치를 사용하세요. WANDB_BASE_URL 환경 변수를 인스턴스 URL로 설정하세요.

​

로컬 사전 요구 사항

서버를 로컬에서 실행하려면 다음이 준비되어 있어야 합니다:

• Python 3.11 이상
• uv 또는 pip
• WANDB_API_KEY로 설정된 W&B API 키
• Dedicated Cloud 또는 Self-Managed를 사용하는 경우, 인스턴스 URL로 설정된 WANDB_BASE_URL

​

서버 설치

설치 방법을 선택한 다음 다음 명령어를 실행해 MCP 서버를 설치하세요:

uvx (영구 설치 없이)

uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

uv

uv pip install wandb-mcp-server

pip

pip install wandb-mcp-server

GitHub에서 설치

pip install git+https://github.com/wandb/wandb-mcp-server

​

클라이언트 설정

MCP 클라이언트를 선택한 다음 아래 설정을 실행하세요. 필요에 따라 <your-wandb-api-key>를 W&B API 키로 바꾸세요:

Claude Code

다음 명령어를 실행하세요. 전역 설정을 하려면 --scope user를 추가하세요.

claude mcp add wandb \
  -e WANDB_API_KEY=<your-wandb-api-key> \
  -e WANDB_BASE_URL=https://your-wandb-instance.example.com \
  -- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

Claude Desktop

Claude Desktop 설정 파일을 여세요:

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

다음 JSON을 추가하세요. 그렇지 않으면 Claude Desktop이 PATH에서 uvx를 찾지 못할 수 있으므로 uvx의 전체 경로를 사용하세요.

{
  "mcpServers": {
    "wandb": {
      "command": "/full/path/to/uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-wandb-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

설정을 적용하려면 Claude Desktop을 다시 시작하세요.

Codex

codex mcp add wandb \
  --env WANDB_API_KEY=<your-wandb-api-key> \
  --env WANDB_BASE_URL=https://your-wandb-instance.example.com \
  -- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

Cursor

다음 내용을 mcp.json 설정에 추가하세요:

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-wandb-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

기본 W&B API endpoint를 사용하려면 WANDB_BASE_URL을 생략하세요.

VS Code

다음 내용을 .vscode/mcp.json 또는 전역 MCP 설정에 추가하세요:

{
  "servers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "<your-wandb-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

​

HTTP 전송으로 서버 실행

웹 기반 클라이언트 또는 테스트용으로는 HTTP 전송을 사용해 서버를 실행하세요:

uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 8080

OpenAI Responses API와 같은 외부 클라이언트에 로컬 서버를 노출하려면 터널을 사용하세요:

uvx wandb_mcp_server --transport http --port 8080

# 다른 터미널에서
ngrok http 8080

터널 URL을 사용하도록 MCP 클라이언트 설정을 업데이트하세요.

​

환경 변수

다음 환경 변수는 로컬 설치 환경에서 인증, 인스턴스 라우팅, 서버 동작을 제어합니다. 클라이언트의 env 블록에 설정하거나 셸에서 export하세요.

Variable	Description
WANDB_API_KEY	인증에 사용하는 W&B API 키입니다. 필수입니다.
WANDB_BASE_URL	Dedicated Cloud 또는 Self-Managed용 맞춤형 W&B 인스턴스 URL입니다. 기본값은 https://api.wandb.ai입니다.
WANDB_MCP_PROXY_DOCS	search_wandb_docs_tool 문서 검색 프록시를 활성화합니다. 기본값: true.
WANDBOT_BASE_URL	문서 검색 프록시용 맞춤형 엔드포인트입니다.
MAX_RESPONSE_TOKENS	도구 응답 잘림에 사용할 토큰 한도입니다. 기본값: 30000.
MCP_SERVER_LOG_LEVEL	로그 상세 수준입니다. DEBUG, INFO, WARNING, ERROR 중 하나입니다.

전체 명령줄 레퍼런스와 고급 옵션은 wandb-mcp-server README를 참조하세요.

​

W&B MCP Server 기능

MCP 서버를 사용해 실험을 분석하고, 트레이스를 디버깅하고, Reports를 생성하고, 레지스트리와 아티팩트를 관리하고, W&B 문서에 관한 질문에 답할 수 있습니다. 다음 예시 프롬프트는 에이전트가 W&B MCP Server에 연결되었을 때 수행하도록 요청할 수 있는 작업의 일부를 보여줍니다.

• “your-team/your-project에서 eval/accuracy 기준 상위 5개 run을 보여줘.”
• “내 채용 에이전트의 predict 트레이스 지연 시간은 지난 한 달 동안 어떻게 변화했나요?”
• “지난주 채용 에이전트가 내린 결정을 비교하는 W&B Reports를 생성해줘.”
• “production-model 아티팩트에는 어떤 버전이 있으며, v2와 v3 사이에 무엇이 변경되었나요?”
• “Weave에서 리더보드를 어떻게 만드나요?”

​

사용 가능한 도구

서버는 다양한 용도로 여러 도구를 제공합니다. 다음 표에는 각 도구의 이름, 에이전트가 해당 도구를 사용해야 하는 경우, 그리고 그 도구를 호출할 때 사용할 수 있는 구체적인 프롬프트가 나와 있습니다.

검색

프로젝트와 entity 이름을 찾고 스키마를 확인하는 데 도움이 되는 도구입니다.

Tool	사용하는 경우	예시 프롬프트
list_entities_tool	entity가 지정되지 않았거나, API 키로 액세스할 수 있는 팀과 계정을 나열해야 하는 경우입니다.	”내가 액세스할 수 있는 W&B 팀은 무엇인가요?”
query_wandb_entity_projects	entity는 알고 있지만 프로젝트 이름은 모르거나, 이전 쿼리가 “project not found”로 실패한 경우입니다.	”your-team 아래의 모든 프로젝트를 나열하세요.”
probe_project_tool	익숙하지 않은 run 기반 프로젝트에서 사용 가능한 메트릭, 설정 키, tags를 파악해야 하는 경우입니다.	”your-team/your-project를 살펴보고 어떤 메트릭이 로깅되는지 알려주세요.”
infer_trace_schema_tool	익숙하지 않은 Weave 트레이스 프로젝트를 쿼리하기 전에 필드 이름, 유형, 샘플 값을 파악해야 하는 경우입니다.	”your-team/your-project의 Weave 트레이스에는 어떤 필드가 있나요?”

Experiments 및 Runs

W&B Models의 run을 쿼리, 비교, 진단하는 도구입니다.

Tool	Use when	Example prompt
query_wandb_tool	질문이 W&B Models의 run, Sweeps, 설정, 요약 또는 아티팩트에 관한 경우에 사용합니다. GraphQL 쿼리를 실행합니다.	”your-team/your-project에서 eval/accuracy 기준 상위 5개 run을 보여주세요.”
get_run_history_tool	질문이 트레이닝 곡선, 시간에 따른 metric 추이 또는 run에 로깅된 시계열 데이터에 관한 경우에 사용합니다.	”your-team/your-project의 run abc123에 대한 loss 곡선을 그려주세요.”
compare_runs_tool	질문이 두 run 사이에 무엇이 달라졌는지, 또는 두 run 중 어느 쪽이 더 나은지에 관한 경우에 사용합니다. 설정 diff, metric 변화량, 선택적 정렬 이력을 반환합니다.	”your-team/your-project에서 run abc123와 def456를 비교해주세요.”
diagnose_run_tool	질문이 run이 수렴했는지, 과적합되고 있는지, 또는 NaN 값이 발생했는지에 관한 경우에 사용합니다. 실행 가능한 권장 사항을 반환합니다.	”your-team/your-project의 run abc123는 과적합되고 있나요?”

Weave 트레이스

LLM 트레이스와 평가를 쿼리하고 집계하는 도구입니다.

Tool	Use when	Example prompt
query_weave_traces_tool	트레이스 데이터가 필요할 때 사용합니다(LLM 호출, 평가, 에이전트 실행). detail_level="summary"로 시작하고, 특정 트레이스에 대해서만 "full"로 높이세요.	”지난 24시간 동안 your-team/your-project에서 실패한 트레이스를 보여주세요.”
count_weave_traces_tool	질문이 트레이스 개수나 오류 개수에 관한 것이고, 트레이스 데이터 자체는 필요하지 않을 때 사용합니다.	”이번 주에 your-team/your-project에서 실패한 트레이스는 몇 개인가요?”
resolve_trace_roots_tool	query_weave_traces_tool로 하위 트레이스를 찾은 뒤, 각 트레이스를 해당 루트 세션 또는 워크플로에 한 번의 배치 호출로 매핑할 때 사용합니다.	”rate limit를 포함하는 LLM 호출을 찾고, 어떤 세션에 속하는지 알려주세요.”
summarize_evaluation_tool	질문이 eval 결과, 통과율 또는 가장 많이 실패하는 작업에 관한 것일 때 사용합니다. Evaluation.evaluate 계층을 집계합니다.	”your-team/your-project의 가장 최근 eval을 요약해주세요.”

Reports

분석 결과를 W&B에 다시 저장하는 도구입니다.

Tool	Use when	Example prompt
create_wandb_report_tool	리포트를 만들거나 결과를 저장해 달라는 명시적 요청이 있을 때 사용합니다. Markdown과 선형 플롯, 막대 플롯, run 비교용 panels 배열을 받습니다.	”run abc123와 def456를 비교하는 W&B 리포트를 만들어 주세요.”
log_analysis_to_wandb	MCP 세션에서 계산된 값(지연 시간 분포, 오류 세부 내역)을 리포트에서 참조하기 전에 분석 run으로 저장해야 할 때 사용합니다.	”이 지연 시간 백분위수를 분석 run으로 W&B에 기록해 주세요.”

Artifacts와 레지스트리

모델, 데이터셋 및 기타 버전이 지정된 아티팩트를 검사하고 차이를 비교할 수 있는 도구입니다.

Tool	Use when	Example prompt
list_registries_tool	질문이 조직의 모델 레지스트리, Registered Models 또는 등록된 데이터셋에 관한 경우 사용합니다.	”your-org에는 어떤 레지스트리가 있나요?”
list_registry_collections_tool	특정 레지스트리 안에 어떤 모델 또는 데이터셋이 있는지 확인할 때 사용합니다.	”your-org의 model 레지스트리에는 어떤 컬렉션이 있나요?”
list_artifact_versions_tool	모델, 데이터셋 또는 기타 아티팩트 컬렉션의 사용 가능한 버전을 나열할 때 사용합니다.	”your-team/your-project의 production-model 버전을 나열해 주세요.”
get_artifact_details_tool	리니지와 파일을 포함해 특정 아티팩트 버전 하나를 검사할 때 사용합니다.	”production-model:v3에는 무엇이 들어 있나요?”
compare_artifact_versions_tool	두 아티팩트 버전 사이에서 무엇이 변경되었는지 확인할 때 사용합니다.	”production-model:v2와 production-model:v3의 차이를 보여주세요.”

문서

공식 W&B 문서의 제품 관련 질문에 답하는 도구입니다.

Tool	사용 시점	예시 프롬프트
search_wandb_docs_tool	질문이 W&B 또는 Weave 기능이나 API 사용 방법에 관한 경우입니다. docs.wandb.ai를 프록시합니다.	”Weave에서 리더보드를 만들려면 어떻게 하나요?”

​

스키마 우선 트레이스 쿼리

Weave 트레이스 쿼리에서는 먼저 infer_trace_schema_tool을 호출해 사용 가능한 필드를 확인한 다음, 정확한 column 목록과 detail_level을 지정해 query_weave_traces_tool을 호출하세요:

detail_level	반환값	사용 시점
schema	구조 필드만 반환합니다. 가장 빠릅니다.	둘러보거나 개수를 셀 때
summary	잘린 inputs 및 outputs를 반환합니다. 기본값입니다.	대부분의 분석 작업
full	잘리지 않은 전체 내용을 반환합니다.	소수의 특정 트레이스를 자세히 확인할 때

이 패턴을 사용하면 광범위한 질문에 대한 token 사용량을 낮게 유지하고, 중요한 트레이스에 대해서만 에이전트가 full로 확장할 수 있습니다.

​

사용 팁

다음 권장 사항과 워크플로를 따르면 W&B MCP Server를 사용할 때 더 나은 결과를 얻을 수 있습니다. 먼저 일반적인 권장 사항부터 살펴본 다음, 더 구체적인 조언과 여러 단계의 도구 체인이 필요한 경우에는 자신의 워크로드에 맞는 하위 섹션을 조회하세요.

​

일반적인 모범 사례

사용 사례와 관계없이 다음 권장 사항을 따르세요:

• entity와 프로젝트를 지정하세요. MCP 도구에는 명시적인 entity(팀 또는 개인 계정)와 프로젝트 이름이 필요합니다. 모든 질문에 이 두 가지를 모두 포함하세요. 예: “your-team/your-project에서”
• 구체적인 질문을 하세요. “내 최고의 평가는 무엇인가요?”보다는 “어떤 eval이 가장 높은 F1 score를 기록했나요?”라고 묻는 편이 좋습니다. 구체적인 메트릭과 시간 범위를 지정하면 더 나은 도구 Call이 생성됩니다.
• 전체 조회인지 확인하세요. “가장 성능이 좋은 Runs는 무엇인가요?”와 같은 광범위한 질문의 경우, 가장 최근 run만이 아니라 사용 가능한 모든 Runs를 조회했는지 에이전트에 확인하도록 요청하세요.
• W&B Skills와 함께 사용하세요. W&B Skills는 코딩 에이전트가 W&B 워크플로를 구성하는 방법을 알려줍니다. Skills는 패턴을 제공하고 MCP는 데이터 액세스를 제공하므로, 두 기능을 함께 사용하면 효과적입니다.

​

트레이스 중심 워크플로의 경우

Weave 트레이스로 작업할 때는 다음 권장 사항을 따르세요.

• 스키마부터 시작하세요. 에이전트가 어떤 필드와 필터 값이 유효한지 알 수 있도록 query_weave_traces_tool보다 먼저 infer_trace_schema_tool을 호출하세요.
• 적절한 detail_level을 선택하세요. 둘러볼 때는 schema를, 분석할 때는 summary(기본값)를, 소수의 특정 트레이스를 자세히 확인할 때만 full을 사용하세요.
• resolve_trace_roots_tool을 연이어 사용하세요. 하위 트레이스를 쿼리한 후 결과로 나온 trace_id 목록을 resolve_trace_roots_tool에 전달하면, 각 트레이스를 루트 세션에 한 번의 배치 호출로 매핑할 수 있습니다.
• eval에는 summarize_evaluation_tool을 우선 사용하세요. 이 도구는 Evaluation.evaluate 및 predict_and_score 계층을 자동으로 집계합니다. 원시 트레이스 데이터가 필요할 때만 query_weave_traces_tool을 사용하세요.

전체 워크플로는 실패한 LLM calls 트리아지를 참조하세요.

​

run 중심 워크플로의 경우

W&B Models run으로 작업할 때는 다음 권장 사항을 따르세요:

• 쿼리하기 전에 먼저 프로브하세요. 익숙하지 않은 run 기반 프로젝트에서는 GraphQL 쿼리를 작성하기 전에 probe_project_tool을 호출해 metric 키, 설정 키, tags를 파악하세요.
• 시계열 데이터에는 get_run_history_tool을 사용하세요. GraphQL은 샘플링을 하지 않으므로, loss 곡선과 기타 시계열 데이터에는 get_run_history_tool이 더 빠르고 비용도 더 적게 듭니다.
• 차이 비교는 compare_runs_tool에 맡기세요. 이 도구는 단일 Call로 config 및 metric 델타와 정렬된 이력 데이터를 반환하므로 수동 비교를 피할 수 있습니다.
• 먼저 헬스 체크를 실행하세요. 트레이닝 run이 이상해 보이면, 이력을 수동으로 자세히 살펴보기 전에 diagnose_run_tool을 호출하세요.

엔드투엔드 워크플로는 문제가 있는 트레이닝 run 진단 및 eval 요약과 모델 버전 비교를 참조하세요.

​

Dedicated Cloud 및 Self-Managed의 경우

Multi-tenant가 아닌 배포 환경에서는 다음 사항을 따르세요:

• 인스턴스의 호스팅 서버인 https://<your-instance>/mcp를 우선 사용하는 것이 좋습니다. 이 서버는 클라이언트 측 WANDB_BASE_URL 설정 없이도 Multi-tenant 서버와 동일한 도구를 노출합니다. 호스팅 서버가 아직 활성화되지 않은 경우에만 로컬 설치로 대체하세요.
• 인스턴스를 대상으로 로컬에서 실행하는 경우, 클라이언트의 env 블록에서 WANDB_BASE_URL을 인스턴스 URL로 설정하세요. 이를 설정하지 않으면 서버가 api.wandb.ai를 대상으로 하므로 데이터를 반환하지 않습니다.
• Dedicated Cloud의 요청 속도 제한은 Multi-tenant와 별도로 적용됩니다. 기본값과 변경 요청 방법은 Dedicated Cloud rate limits를 참조하세요.

​

로컬 설치 시

자신의 머신에서 서버를 실행할 때는 다음 권장 사항을 따르세요:

• 데스크톱 클라이언트(Cursor, VS Code, Claude Code, Claude Desktop)에는 STDIO 전송 방식을 우선 사용하세요. 클라이언트가 명시적으로 요구하는 경우에만 HTTP 전송 방식으로 전환하세요(예: OpenAI Responses API).
• 도구 Call이 아무 오류 메시지 없이 실패하면 클라이언트의 env 블록에서 MCP_SERVER_LOG_LEVEL=DEBUG를 설정한 다음, 클라이언트의 MCP 로그를 다시 확인하세요.
• GitHub에서 설치하는 경우(uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server), uvx는 기본 브랜치에 고정됩니다. 안정적인 버전이 필요하면 Git URL 끝에 @v0.3.2를 추가해 명시적인 태그로 고정하세요.

​

권장 워크플로

대부분의 실제 질문에는 두 개 이상의 도구가 필요합니다. 에이전트에게 다음 체인 중 하나를 따르도록 요청하세요.

​

낯선 프로젝트 살펴보기

프로젝트에 무엇이 로깅되었는지 살펴보려면 다음 도구를 순서대로 사용하세요:

1. entity 또는 팀을 찾으려면 list_entities_tool을 사용합니다.
2. 프로젝트를 찾으려면 query_wandb_entity_projects를 사용합니다.
3. run 기반 프로젝트에는 probe_project_tool을, Weave 트레이스 프로젝트에는 infer_trace_schema_tool을 사용합니다.
4. 찾은 키를 사용해 query_wandb_tool 또는 query_weave_traces_tool을 대상에 맞게 호출합니다.

​

실패한 LLM calls 선별하기

문제가 있는 트레이스와 이를 생성한 세션을 찾으려면 다음 도구를 순서대로 연결해 사용하세요:

1. 오류 또는 예외 필드에 Filter를 적용하고 detail_level="summary"로 query_weave_traces_tool을 실행합니다.
2. 결과 trace_id 목록에 resolve_trace_roots_tool을 적용해 각 실패를 해당 루트 세션에 매핑합니다.
3. 일부 특정 루트에 대해 detail_level="full"로 query_weave_traces_tool을 실행해 자세히 살펴봅니다.
4. create_wandb_report_tool로 결과를 문서화합니다.

​

문제가 있는 트레이닝 run 진단하기

의심스러운 트레이닝 run에 대해 헬스 체크를 수행하려면 다음 도구를 순서대로 연결하세요:

1. get_run_history_tool로 loss 및 검증 곡선을 가져옵니다.
2. diagnose_run_tool로 수렴, 과적합, NaN을 자동으로 점검합니다.
3. compare_runs_tool로 정상으로 확인된 기준 run과 비교합니다.
4. create_wandb_report_tool로 선 그래프 Panel이 포함된 report를 만들어 진단 결과를 공유합니다.

​

평가를 요약하고 모델 버전 비교하기

평가에서 어떤 모델 버전이 가장 좋은 성능을 보였는지 확인하려면 다음 도구를 차례대로 사용하세요:

1. 각 Scorer별 통과율과 오류 수를 확인하려면 summarize_evaluation_tool
2. 관련 모델 컬렉션의 list_artifact_versions_tool
3. 후보 버전과 현재 프로덕션 버전을 비교하려면 compare_artifact_versions_tool
4. 비교 결과를 게시하려면 log_analysis_to_wandb 및 create_wandb_report_tool

​

문제 해결

다음 표를 사용하여 W&B MCP 서버 사용 중 발생하는 문제를 진단하고 해결하세요.

증상	원인 및 해결 방법
401 Unauthorized 또는 Invalid API key	W&B API 키가 없거나 형식이 잘못되었거나, 대상 entity 또는 팀에 대한 권한이 없습니다. wandb.ai/authorize에서 키를 다시 생성한 뒤, Bearer 토큰으로 전달되었거나 WANDB_API_KEY에 설정되어 있는지 확인하세요.
성공할 것으로 예상한 쿼리에서 빈 결과가 반환됨	팀/entity 또는 프로젝트 이름이 올바르지 않거나 API 키에 액세스 권한이 없습니다. 에이전트와 함께 두 항목을 모두 확인한 후 다시 시도하세요.
https://<your-instance>/mcp에서 404 Not Found 또는 connection refused 발생	호스팅된 MCP 서버가 Dedicated Cloud 또는 Self-Managed 인스턴스에서 아직 활성화되지 않았거나, 클라이언트가 잘못된 URL을 가리키고 있습니다. 활성화를 요청하려면 W&B 지원팀에 문의한 다음, Connection URL에서 URL을 확인하세요.
Dedicated Cloud에서 429 Too Many Requests 발생	인스턴스의 요청 속도 제한에 도달했습니다. 더 높은 제한을 요청하는 방법은 Dedicated Cloud rate limits를 참조하세요.
Claude Desktop에서 로컬 서버가 uvx를 찾지 못함	claude_desktop_config.json의 command 필드에 uvx의 전체 경로를 사용하세요.