AI 어시스턴트에서 Weights & Biases 사용하기

Weights & Biases는 서로 보완적인 두 가지 방식으로 AI 어시스턴트와 연동됩니다.

W&B Skills는 코딩 에이전트가 코드와 분석 워크플로에서 Weights & Biases를 효과적으로 사용하는 방법을 알려 줍니다.
Weights & Biases MCP 서버는 AI 어시스턴트를 Weights & Biases 데이터 및 문서에 연결하여, 어시스턴트가 run, 트레이스, 평가, 아티팩트에 관한 자연어 질문에 답할 수 있게 합니다.

코딩 에이전트가 Weights & Biases를 활용하는 코드를 작성하거나 수정하게 하려면 Skills를 사용하세요. AI 어시스턴트가 실시간 Weights & Biases 데이터를 쿼리하거나 Weights & Biases 문서를 검색하게 하려면 MCP 서버를 사용하세요. 두 가지를 함께 사용하면 더욱 효과적입니다. Skills는 워크플로 패턴을, MCP는 데이터 액세스를 제공합니다. Weights & Biases는 인테그레이션에 따라 다음과 같은 주요 코딩 에이전트, IDE, 채팅 어시스턴트와 함께 사용할 수 있습니다.

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

W&B Skills에서 지원하는 에이전트의 전체 목록은 W&B Skills CLI 문서를 참조하세요.

W&B Skills

W&B Skills는 코딩 에이전트가 Weights & Biases를 효과적으로 사용하는 방법을 익힐 수 있도록 하는 재사용 가능한 지침 모음입니다. W&B API와 모범 사례를 에이전트에게 일일이 안내하는 대신 Skills를 설치하세요. 그러면 에이전트가 실험 추적, 트레이싱, 평가, 모니터링 작업을 스스로 수행할 수 있습니다.

기능

Skills는 W&B Python SDK(트레이닝 run, 메트릭, 아티팩트, 스윕)와 Weave SDK(트레이스, 평가, Scorer)를 모두 지원합니다. 헬퍼 라이브러리, 레퍼런스 문서, 데이터 분석 패턴이 포함되어 있어 에이전트가 다음 워크플로를 처리할 수 있습니다.

워크플로	기능
모델 트레이닝	트레이닝 및 파인튜닝 중에 메트릭과 리치 미디어를 로깅합니다. 실험을 추적하고 비교합니다. 손실 곡선, 정확도 점수 등 run과 결과를 분석합니다. 하이퍼파라미터를 튜닝합니다.
에이전트 구축	에이전트형 AI 애플리케이션을 트레이싱합니다. 트레이스를 분석하고 실패 유형을 분류합니다. 레이블이 지정된 데이터셋으로 모델과 에이전트를 평가합니다. 프로덕션 모니터링을 위해 온라인 평가를 실행합니다.

사전 요구 사항

W&B Skills를 사용하려면 다음이 필요합니다.

npx 명령을 실행하기 위한 Node.js
Forge API 키. forge.coreweave.com/settings#apikeys에서 API 키를 생성한 다음 환경 변수로 설정하세요. [YOUR-API-KEY]를 본인의 API 키로 바꾸세요.
export WANDB_API_KEY="[YOUR-API-KEY]"
선택: Weights & Biases 프로젝트 이름을 WANDB_PROJECT 환경 변수로 설정하세요. 이렇게 하면 매번 프로젝트를 지정하지 않아도 에이전트가 올바른 Weights & Biases 프로젝트에서 작업할 수 있습니다.

W&B Skills 설치

모든 프로젝트에서 Skills를 사용하려면 전역 설치를, 특정 프로젝트에서만 Skills를 사용하려면 프로젝트별 설치를 선택하세요. 모든 프로젝트에서 사용할 수 있도록 W&B Skills를 전역으로 설치하려면 --global 플래그를 사용하세요.

npx skills add wandb/skills --skill '*' --yes --global

현재 프로젝트에만 Skills를 설치하려면 프로젝트 디렉터리에서 --global 플래그 없이 설치 명령을 실행하세요.

npx skills add wandb/skills --skill '*' --yes

--agent 플래그를 사용하면 특정 에이전트용 Skills를 설치할 수 있습니다.

npx skills add wandb/skills \
  --agent claude-code \
  --skill '*' \
  --yes \
  --global

--agent 및 --skill 옵션 목록은 Vercel Labs skills CLI 문서를 참조하세요. 설치가 완료되면 에이전트가 W&B Skills에 액세스할 수 있으며, Weights & Biases 관련 작업을 처리할 수 있습니다.

W&B Skills 사용하기

에이전트에게 프로젝트와 관련된 Weights & Biases 작업을 요청하세요. 다음 예시 프롬프트는 에이전트가 W&B Skills로 수행할 수 있는 작업 중 일부를 보여줍니다.

“내 PyTorch 모델의 트레이닝 메트릭을 Weights & Biases에 로깅해 줘.”
“최근 run 10개의 손실 곡선을 분석해서 성능이 가장 좋은 설정을 파악해 줘.”
“내 LangChain 에이전트를 트레이스하고 결과를 Weave에 로깅해 줘.”
“테스트 데이터셋으로 내 에이전트를 평가하고 결과를 요약해 줘.”
“최근 평가에서 실패 유형을 찾아서 분류해 줘.”
“run A와 run B의 설정을 비교해서 차이를 보여 줘.”

W&B Skills 사용 팁

Skills는 광범위하고 막연한 질문보다 구체적인 질문에 더 좋은 결과를 제공합니다. 다음 표에서 권장 프롬프트와 지나치게 모호한 프롬프트를 비교해 보세요.

권장	권장하지 않음
”최근 run 5개의 최종 검증 손실은 얼마인가요?"	"내 모델 상태는 어떤가요?"
"최근 트레이스 10개의 토큰 사용량을 요약해 주세요."	"내 트레이스를 모두 보여 주세요."
"run A와 run B의 설정을 비교해 주세요."	"가장 좋은 run은 무엇인가요?"
"F1 점수가 가장 높은 평가는 무엇인가요?"	"내 평가는 어떻게 진행되고 있나요?”

Weights & Biases MCP 서버

Model Context Protocol(MCP)은 AI 에이전트가 외부 도구를 호출할 수 있도록 하는 개방형 표준입니다. Weights & Biases MCP 서버를 사용하면 IDE, 코딩 어시스턴트, 채팅 에이전트가 Weights & Biases 데이터와 문서에 직접 액세스할 수 있습니다. 따라서 에이전트가 복사해서 붙여넣는 과정 없이도 run, 트레이스, 평가, 아티팩트에 관한 질문에 답할 수 있습니다. 서버로 할 수 있는 작업에 대한 자세한 내용은 Weights & Biases MCP 서버 기능 섹션을 참조하세요.

배포 유형

Weights & Biases MCP 서버는 두 가지 배포 옵션을 제공합니다. 가장 빠르게 설정하려면 호스팅 서버를 사용하고, 더 높은 격리 수준과 유연성이 필요하다면 로컬 버전을 설정하세요. 로컬 버전을 사용하는 경우 클라이언트가 서버에 액세스할 때 다른 URL을 사용해야 합니다.

호스팅 서버(권장)

Weights & Biases가 관리하는 MCP 서버로, 클라이언트가 API 키를 사용해 HTTP로 연결합니다. 별도로 설치하거나 유지 관리할 로컬 프로세스가 없습니다.호스팅 서버 사용하기

로컬 설치

STDIO 또는 HTTP를 통해 자체 머신에서 MCP 서버를 실행합니다. 에어갭 환경에서 운영해야 하거나, 특정 릴리스로 버전을 고정하거나, 서버 동작을 맞춤형으로 변경하거나, 서버를 직접 개발 중이거나, STDIO만 지원하는 클라이언트를 사용해야 할 때 적합합니다.로컬에서 MCP 서버 실행하기

사전 요구 사항

클라이언트를 설정하기 전에 다음 사항이 준비되어 있는지 확인하세요.

forge.coreweave.com/settings#apikeys에서 API 키를 생성하세요.
키를 WANDB_API_KEY 환경 변수로 설정하거나, 클라이언트에 Bearer 토큰으로 전달하세요.
Dedicated Cloud, Self-Managed, 그리고 기본 인스턴스가 아닌 인스턴스에 연결하는 로컬 설치 환경에서는 WANDB_BASE_URL 환경 변수를 해당 인스턴스 URL로 설정하세요.
Weights & Biases는 mcp SDK 버전을 1.14.0(릴리스 2024-11-05)으로 고정합니다. 클라이언트는 mcp SDK 1.14.x로 연결해야 합니다. W&B Dedicated Cloud에서 Streamable HTTP를 사용하려면 mcp SDK 1.14.x 릴리스 2025-03-26 이상이 필요합니다.

호스팅 서버 사용하기

Weights & Biases는 모든 배포 유형에서 관리형 MCP 서버를 제공합니다. 별도로 설치할 필요가 없습니다. Authorization 헤더에 API 키를 넣어 HTTP로 연결하도록 클라이언트를 설정하세요.

연결 URL

URL은 Weights & Biases 배포 유형에 따라 다릅니다.

배포	서버 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을 기준으로 합니다.

Bearer 토큰을 본인의 API 키로 바꾼 후 Claude Code에 Weights & Biases MCP 서버를 등록하세요.

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을 호출하여 사용자 이름과 소속 팀을 반환하면 정상입니다. 연결에 실패하면 문제 해결을 참조하세요. 자세한 내용은 Claude Code의 MCP 문서를 참조하세요.

Claude Desktop의 기본 제공 맞춤형 커넥터 인터페이스는 원격 MCP 서버에 대한 API 키 인증을 지원하지 않습니다. 이 제한을 우회하려면 mcp-remote npm 프록시를 사용하여 Claude Desktop을 Weights & Biases 원격 MCP 서버에 연결하세요. 이 프록시는 로컬에서 실행되며, 요청을 Bearer 토큰과 함께 https://mcp.withwandb.com/mcp로 전달합니다.시스템에 Node.js가 설치되어 있어야 합니다.텍스트 편집기에서 Claude Desktop 설정 파일을 여세요. 운영 체제별 설정 파일 위치는 다음과 같습니다.

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

설정 파일의 JSON 객체에 다음 내용을 추가하고, [YOUR-WANDB-API-KEY]를 본인의 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을 호출하여 사용자 이름과 소속된 팀을 반환하면 정상입니다. 연결에 실패하면 문제 해결을 참조하세요.

API 키를 환경 변수로 내보낸 다음 Codex에 서버를 등록하세요.

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에 서버를 자동 설치한 다음, Authorization 필드의 플레이스홀더를 본인의 API 키로 바꾸세요.Cursor를 수동으로 설정하려면 다음 단계를 따르세요.

macOS에서는 Cursor > Settings > Cursor Settings를 여세요. Windows 또는 Linux에서는 Preferences > Settings > Cursor Settings를 여세요.
Tools and MCP를 선택하세요.
Installed MCP Servers에서 Add Custom MCP를 선택하세요. Cursor에서 mcp.json 설정 파일이 열립니다.

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

{
  "mcpServers": {
    "wandb": {
      "transport": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer [YOUR-WANDB-API-KEY]",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Cursor를 다시 시작하세요.
List my W&B entities.라고 질문해 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하여 사용자 이름과 소속된 팀을 반환하면 정상입니다.

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

Weights & Biases MCP 확장을 설치하세요.

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

Gemini CLI를 다시 시작하세요. List my W&B entities.라고 요청하여 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하여 사용자 이름과 소속된 모든 팀을 반환하면 정상입니다.연결에 실패하면 문제 해결을 참조하세요. 자세한 내용은 Gemini CLI MCP 문서를 참조하세요.

LeChat에서 Intelligence 메뉴를 열고 Add Connector를 선택하세요.
Custom MCP Connector를 선택하세요.
다음 필드를 설정하세요.
- Connector Server: https://mcp.withwandb.com/mcp
- Description: (선택) 간단한 설명
- Authentication Method: API Token Authentication을 선택하세요.
- Header name: Authorization을 그대로 두세요.
- Header type: Bearer를 선택하세요.
- Header value: 본인의 API 키
Create를 선택하세요.
List my W&B entities.라고 질문하여 연결을 확인하세요. 에이전트가 list_entities_tool을 호출하여 사용자 이름과 소속된 모든 팀을 반환하면 정상입니다.

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

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)

API 키 원본 값을 authorization 값으로 전달하세요. OpenAI가 서버를 호출할 때 Bearer 를 자동으로 앞에 붙이므로 직접 추가하지 마세요. OpenAI MCP 인테그레이션은 서버 측에서 실행되므로 로컬 MCP 서버에는 접근할 수 없습니다. 로컬에서 개발하는 경우 MCP 서버를 로컬에서 실행하기를 참조하세요.

전역 또는 워크스페이스의 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을 호출하여 사용자 이름과 소속된 팀을 반환하면 정상입니다.연결에 실패하면 문제 해결을 참조하세요.

MCP 서버를 로컬에서 실행

로컬 설치는 호스팅 서버를 대신하는 선택지이며, 어떤 배포 유형에서도 기본 방식이 아닙니다. 호스팅 서버가 현재 설정에 맞지 않을 때 로컬 설치를 사용하세요. 로컬에서 실행하는 일반적인 이유는 다음과 같습니다.

에어갭 또는 오프라인 환경: 클라이언트가 호스팅된 Weights & Biases 엔드포인트에 연결할 수 없는 경우
버전 고정: 호스팅 서버는 main 브랜치를 따르지만, 로컬 설치에서는 특정 릴리스 태그로 버전을 고정할 수 있습니다.
맞춤형 서버 동작: 도구 설명 변경, 도구 추가, 기본값이 아닌 응답 토큰 예산 설정 등
서버 자체 개발: 서버를 직접 개발하고 있는 경우
STDIO 전용 클라이언트 또는 로컬 프로세스가 필요한 클라이언트

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

로컬 사전 요구 사항

서버를 로컬에서 실행하려면 다음 항목이 준비되어 있는지 확인하세요.

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

서버 설치

설치 방법을 선택한 다음 아래 명령을 실행하여 MCP 서버를 설치하세요.

uvx (영구 설치 없이 실행)
uv
pip
GitHub에서 설치

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

uv pip install wandb-mcp-server

pip install wandb-mcp-server

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

클라이언트 설정하기

서버를 설치했으면 서버를 실행하도록 클라이언트를 설정하세요. 사용하는 MCP 클라이언트를 선택한 다음 아래 설정을 실행하고, 필요한 경우 [YOUR-WANDB-API-KEY]를 본인의 API 키로 바꾸세요.

Claude Code
Claude Desktop
Codex
Cursor
VS Code

로컬 서버를 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 설정 파일을 여세요.

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 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

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 엔드포인트를 사용하려면 WANDB_BASE_URL을 생략하세요.

.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하세요.

변수	설명
`WANDB_API_KEY`	인증에 사용할 API 키입니다. 필수 항목입니다.
`WANDB_BASE_URL`	Dedicated Cloud 또는 Self-Managed 환경에서 사용할 맞춤형 Weights & Biases 인스턴스 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를 참조하세요.

Weights & Biases MCP 서버 기능

MCP 서버를 사용하면 실험 분석, 트레이스 디버깅, 리포트 작성, 레지스트리 및 아티팩트 관리는 물론 Weights & Biases 문서를 바탕으로 한 질문 답변까지 할 수 있습니다. 다음 예시 프롬프트는 에이전트가 Weights & Biases MCP 서버에 연결되어 있을 때 요청할 수 있는 작업의 일부를 보여 줍니다.

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

사용 가능한 도구

서버는 용도별로 분류된 여러 도구를 제공합니다. 다음 표에서는 각 도구의 이름, 에이전트가 해당 도구를 사용해야 하는 상황, 그리고 해당 도구를 호출하는 데 사용할 수 있는 구체적인 프롬프트 예시를 확인할 수 있습니다.

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

도구	사용 시점	예시 프롬프트
`list_entities_tool`	entity가 지정되지 않았거나, API 키로 액세스할 수 있는 팀과 계정을 나열하려는 경우	”내가 액세스할 수 있는 Weights & Biases 팀은 무엇인가요?”
`query_wandb_entity_projects`	entity는 알지만 프로젝트 이름을 모르거나, 이전 쿼리가 “project not found” 오류로 실패한 경우	”`your-team`에 속한 모든 프로젝트를 나열해 줘.”
`probe_project_tool`	처음 접하는 run 기반 프로젝트에서 사용 가능한 메트릭, 설정 키, 태그를 파악하려는 경우	”`your-team/your-project`를 살펴보고 어떤 메트릭이 로깅되었는지 알려 줘.”
`infer_trace_schema_tool`	처음 접하는 Weave 트레이스 프로젝트를 쿼리하기 전에 필드 이름, 유형, 샘플 값을 파악하려는 경우	”`your-team/your-project`의 Weave 트레이스에는 어떤 필드가 있나요?”

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

도구	사용 시점	프롬프트 예시
`query_wandb_tool`	Weights & Biases의 run, 스윕, 설정, 요약 또는 아티팩트에 관해 질문할 때 사용합니다. GraphQL 쿼리를 실행합니다.	”`your-team/your-project`에서 `eval/accuracy` 기준 상위 5개 run을 보여 줘.”
`get_run_history_tool`	트레이닝 곡선, 시간에 따른 메트릭 추세 또는 run에 로깅된 시계열 데이터에 관해 질문할 때 사용합니다.	”`your-team/your-project`에 있는 run `abc123`의 loss 곡선을 그려 줘.”
`compare_runs_tool`	두 run 사이에 무엇이 달라졌는지, 또는 어느 run이 더 나은지 질문할 때 사용합니다. 설정 차이, 메트릭 델타와 함께 정렬된 이력(선택)을 반환합니다.	”`your-team/your-project`에서 run `abc123`과 `def456`을 비교해 줘.”
`diagnose_run_tool`	run이 수렴했는지, 과적합되고 있는지, NaN 값이 발생했는지 질문할 때 사용합니다. 구체적인 권장 사항을 반환합니다.	”`your-team/your-project`에 있는 run `abc123`이 과적합되고 있어?”

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

도구	사용 시점	예시 프롬프트
`query_weave_traces_tool`	트레이스 데이터(LLM Call, 평가, 에이전트 run)가 필요한 경우. `detail_level="summary"`로 시작하고, 특정 트레이스에 한해서만 `"full"`로 높이세요.	”`your-team/your-project`에서 지난 24시간 동안 실패한 트레이스를 보여줘.”
`count_weave_traces_tool`	트레이스 데이터 자체는 필요 없고 트레이스 수나 오류 수만 알고 싶은 경우.	”이번 주에 `your-team/your-project`에서 실패한 트레이스는 몇 개야?”
`resolve_trace_roots_tool`	`query_weave_traces_tool`로 하위 트레이스를 찾은 뒤, 한 번의 일괄 Call로 각 트레이스를 해당 루트 세션 또는 워크플로에 매핑하려는 경우.	”`rate limit`이 포함된 LLM Call을 찾아서 각각 어떤 세션에 속하는지 알려줘.”
`summarize_evaluation_tool`	평가 결과, 통과율, 가장 자주 실패하는 작업 등을 알고 싶은 경우. `Evaluation.evaluate` 계층 구조를 집계합니다.	”`your-team/your-project`의 가장 최근 평가를 요약해줘.”

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

도구	사용 시점	예시 프롬프트
`create_wandb_report_tool`	리포트 생성이나 발견 사항 저장을 명시적으로 요청한 경우. Markdown과 함께 선형 플롯, 막대 플롯, run 비교용 `panels` 배열을 입력받습니다.	”run `abc123`과 `def456`을 비교하는 W&B 리포트를 만들어 주세요.”
`log_analysis_to_wandb`	MCP 세션에서 계산한 값(지연 시간 분포, 오류 유형별 분석 등)을 리포트에서 참조하기 전에 run으로 저장해야 하는 경우.	”이 지연 시간 백분위수를 Weights & Biases에 분석 run으로 로깅해 주세요.”

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

도구	사용 시점	예시 프롬프트
`list_registries_tool`	조직의 모델 레지스트리, 등록된 모델 또는 등록된 데이터셋에 관해 질문할 때	”`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`을 비교해 주세요.”

공식 Weights & Biases 문서를 바탕으로 제품 관련 질문에 답변하는 도구입니다.

도구	사용 시점	예시 프롬프트
`search_wandb_docs_tool`	Weights & Biases 또는 Weave의 기능이나 API 사용 방법을 알고 싶을 때 사용합니다. docs.wandb.ai의 프록시 역할을 합니다.	”Weave에서 리더보드를 만들려면 어떻게 해야 하나요?”

스키마 우선 트레이스 쿼리

Weave 트레이스를 쿼리할 때는 먼저 infer_trace_schema_tool을 호출하여 사용 가능한 필드를 확인한 다음, 필요한 열 목록과 detail_level을 정확히 지정하여 query_weave_traces_tool을 호출하세요.

`detail_level`	반환값	사용 시점
`schema`	구조 필드만 반환합니다. 가장 빠릅니다.	탐색하거나 개수를 셀 때
`summary`	입력과 출력을 잘라서 반환합니다. 기본값입니다.	대부분의 분석 작업
`full`	모든 내용을 자르지 않고 반환합니다.	소수의 특정 트레이스를 자세히 분석할 때

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

사용 팁

다음 섹션에서는 Weights & Biases MCP 서버를 더 효과적으로 활용하는 데 도움이 되는 권장 사례와 워크플로를 설명합니다. 먼저 일반적인 권장 사례를 살펴본 다음, 사용 중인 워크로드에 해당하는 섹션에서 더 구체적인 조언과 여러 단계로 이루어진 도구 체인을 확인하세요.

일반 모범 사례

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

entity와 프로젝트를 지정하세요. MCP 도구를 사용하려면 entity(팀 또는 개인 계정)와 프로젝트 이름을 명시해야 합니다. “in your-team/your-project”와 같이 모든 질문에 두 가지를 모두 포함하세요.
구체적으로 질문하세요. “What is my best evaluation?”보다는 “Which eval had the highest F1 score?”처럼 질문하는 것이 좋습니다. 메트릭과 기간을 구체적으로 지정할수록 더 적절한 도구 Call이 생성됩니다.
전체 조회 여부를 확인하세요. “What are my best performing runs?”처럼 범위가 넓은 질문을 할 때는 에이전트가 가장 최근 run만이 아니라 사용 가능한 모든 run을 조회했는지 확인하도록 요청하세요.
W&B Skills와 함께 사용하세요. W&B Skills는 코딩 에이전트에게 Weights & Biases 워크플로를 구성하는 방법을 알려줍니다. 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에 전달하면, 한 번의 일괄 Call로 각 트레이스를 루트 세션에 매핑할 수 있습니다.
평가에는 summarize_evaluation_tool을 우선 사용하세요. 이 도구는 Evaluation.evaluate 및 predict_and_score 계층 구조를 자동으로 집계합니다. query_weave_traces_tool은 원시 트레이스 데이터가 필요할 때만 사용하세요.

엔드투엔드 워크플로는 실패한 LLM Call 분류를 참조하세요.

run 중심 워크플로의 경우

W&B run을 다룰 때는 다음 권장 사항을 따르세요.

쿼리하기 전에 먼저 탐색하세요. 익숙하지 않은 run 기반 프로젝트에서는 GraphQL을 작성하기 전에 probe_project_tool을 호출하여 메트릭 키, 설정 키, 태그를 파악하세요.
시계열 데이터에는 get_run_history_tool을 사용하세요. GraphQL은 샘플링을 하지 않으므로 손실 곡선 같은 시계열 데이터에는 get_run_history_tool이 더 빠르고 비용도 적게 듭니다.
비교는 compare_runs_tool에 맡기세요. 이 도구는 설정 및 메트릭 차이를 정렬된 이력과 함께 단일 Call로 반환하므로 직접 비교할 필요가 없습니다.
먼저 헬스 체크를 실행하세요. 트레이닝 run이 이상해 보이면 이력을 직접 살펴보기 전에 diagnose_run_tool을 호출하세요.

전체 워크플로는 잘못된 트레이닝 run 진단하기 및 평가 요약 및 모델 버전 비교하기를 참조하세요.

Dedicated Cloud 및 Self-Managed의 경우

Multi-tenant가 아닌 배포에서는 다음 권장 사항을 따르세요.

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

로컬 설치의 경우

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

데스크톱 클라이언트(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를 붙여 특정 태그로 고정하세요.

권장 워크플로

실제 질문은 대부분 도구 하나만으로는 해결되지 않습니다. 다음 워크플로는 에이전트에게 요청할 수 있는 일반적인 다단계 도구 체인을 보여 줍니다.

익숙하지 않은 프로젝트 살펴보기

프로젝트에 로깅된 내용을 살펴보려면 다음 도구를 순서대로 연결해 사용하세요.

list_entities_tool로 entity 또는 팀을 찾습니다.
query_wandb_entity_projects로 프로젝트를 찾습니다.
run 기반 프로젝트라면 probe_project_tool을, Weave 트레이스 프로젝트라면 infer_trace_schema_tool을 사용합니다.
앞 단계에서 확인한 키를 사용해 query_wandb_tool 또는 query_weave_traces_tool을 호출하여 필요한 데이터만 조회합니다.

실패한 LLM Call 분류

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

오류 또는 예외 필드에 대한 필터와 detail_level="summary"를 지정해 query_weave_traces_tool을 실행합니다.
결과로 얻은 trace_id 목록에 resolve_trace_roots_tool을 실행해 각 실패를 해당 루트 세션에 매핑합니다.
몇 개의 특정 루트를 골라 detail_level="full"로 query_weave_traces_tool을 실행해 자세히 분석합니다.
create_wandb_report_tool로 발견 사항을 문서화합니다.

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

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

get_run_history_tool로 손실 곡선과 검증 곡선을 가져옵니다.
diagnose_run_tool로 수렴, 과적합, NaN 여부를 자동으로 검사합니다.
compare_runs_tool로 정상 동작이 확인된 기준 run과 비교합니다.
create_wandb_report_tool로 선 플롯 패널이 포함된 리포트를 만들어 진단 결과를 공유합니다.

평가 요약 및 모델 버전 비교

평가에서 가장 성능이 좋았던 모델 버전을 찾으려면 다음 도구를 차례로 연결해 사용하세요.

summarize_evaluation_tool: Scorer별 통과율과 오류 수를 확인합니다.
list_artifact_versions_tool: 해당 모델 컬렉션의 버전 목록을 조회합니다.
compare_artifact_versions_tool: 후보 버전과 현재 프로덕션 버전을 비교합니다.
log_analysis_to_wandb 및 create_wandb_report_tool: 비교 결과를 게시합니다.

문제 해결

다음 표를 참고하여 Weights & Biases MCP 서버 사용 시 발생하는 문제를 진단하고 해결하세요.

증상	원인 및 해결 방법
`401 Unauthorized` 또는 `Invalid API key`	API 키가 없거나, 형식이 잘못되었거나, 대상 entity 또는 팀에 대한 권한이 없습니다. forge.coreweave.com/settings#apikeys에서 키를 다시 생성한 다음, 키가 Bearer 토큰으로 전달되거나 `WANDB_API_KEY`에 설정되어 있는지 확인하세요.
정상적으로 반환되어야 할 쿼리의 결과가 비어 있음	팀, entity 또는 프로젝트 이름이 올바르지 않거나, API 키에 액세스 권한이 없습니다. 에이전트와 함께 두 가지를 모두 확인한 후 다시 시도하세요.
`https://[YOUR-INSTANCE]/mcp`에서 `404 Not Found` 또는 `connection refused` 발생	Dedicated Cloud 또는 Self-Managed 인스턴스에서 호스팅형 MCP 서버가 아직 활성화되지 않았거나, 클라이언트가 잘못된 URL을 가리키고 있습니다. Weights & Biases 지원팀에 문의하여 활성화를 요청한 다음, 연결 URL에서 URL을 확인하세요.
Dedicated Cloud에서 `429 Too Many Requests` 발생	인스턴스의 요청 속도 제한에 도달했습니다. 한도 상향을 요청하는 방법은 Dedicated Cloud 요청 속도 제한을 참조하세요.
Claude Desktop에서 로컬 서버가 `uvx`를 찾지 못함	`claude_desktop_config.json`의 `command` 필드에 `uvx`의 전체 경로를 입력하세요.

​W&B Skills

​기능

​사전 요구 사항

​W&B Skills 설치

​W&B Skills 사용하기

​W&B Skills 사용 팁

​Weights & Biases MCP 서버

​배포 유형

호스팅 서버(권장)

로컬 설치

​사전 요구 사항

​호스팅 서버 사용하기

​연결 URL

​MCP 서버를 로컬에서 실행

​로컬 사전 요구 사항

​서버 설치

​클라이언트 설정하기

​HTTP 전송 방식으로 서버 실행하기

​환경 변수

​Weights & Biases MCP 서버 기능

​사용 가능한 도구

​스키마 우선 트레이스 쿼리

​사용 팁

​일반 모범 사례

​트레이스 중심 워크플로

​run 중심 워크플로의 경우

​Dedicated Cloud 및 Self-Managed의 경우

​로컬 설치의 경우

​권장 워크플로

​익숙하지 않은 프로젝트 살펴보기

​실패한 LLM Call 분류

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

​평가 요약 및 모델 버전 비교

​문제 해결

W&B Skills

기능

사전 요구 사항

W&B Skills 설치

W&B Skills 사용하기

W&B Skills 사용 팁

Weights & Biases MCP 서버

배포 유형

사전 요구 사항

호스팅 서버 사용하기

연결 URL

MCP 서버를 로컬에서 실행

로컬 사전 요구 사항

서버 설치

클라이언트 설정하기

HTTP 전송 방식으로 서버 실행하기

환경 변수

Weights & Biases MCP 서버 기능

사용 가능한 도구

스키마 우선 트레이스 쿼리

사용 팁

일반 모범 사례

트레이스 중심 워크플로

run 중심 워크플로의 경우

Dedicated Cloud 및 Self-Managed의 경우

로컬 설치의 경우

권장 워크플로

익숙하지 않은 프로젝트 살펴보기

실패한 LLM Call 분류

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

평가 요약 및 모델 버전 비교

문제 해결