> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI 어시스턴트에서 Weights & Biases 사용하기
> W&B Skills와 Weights & Biases MCP 서버를 사용하여 워크플로를 자동화하고, 데이터를 쿼리하고, 문서를 검색하세요.
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 문서](https://github.com/vercel-labs/skills#supported-agents)를 참조하세요.
W\&B Skills
W\&B Skills는 코딩 에이전트가 Weights & Biases를 효과적으로 사용하는 방법을 익힐 수 있도록 하는 재사용 가능한 지침 모음입니다. W\&B API와 모범 사례를 에이전트에게 일일이 안내하는 대신 Skills를 설치하세요. 그러면 에이전트가 실험 추적, 트레이싱, 평가, 모니터링 작업을 스스로 수행할 수 있습니다.
기능
Skills는 [W\&B Python SDK](/ko/products/wandb/ref)(트레이닝 run, 메트릭, 아티팩트, 스윕)와 [Weave SDK](/ko/products/wandb/weave/reference/python-sdk)(트레이스, 평가, Scorer)를 모두 지원합니다. 헬퍼 라이브러리, 레퍼런스 문서, 데이터 분석 패턴이 포함되어 있어 에이전트가 다음 워크플로를 처리할 수 있습니다.
| 워크플로 | 기능 |
| - | - |
| **모델 트레이닝** | - 트레이닝 및 파인튜닝 중에 메트릭과 리치 미디어를 로깅합니다.
- 실험을 추적하고 비교합니다.
- 손실 곡선, 정확도 점수 등 run과 결과를 분석합니다.
- 하이퍼파라미터를 튜닝합니다.
|
| **에이전트 구축** | - 에이전트형 AI 애플리케이션을 트레이싱합니다.
- 트레이스를 분석하고 실패 유형을 분류합니다.
- 레이블이 지정된 데이터셋으로 모델과 에이전트를 평가합니다.
- 프로덕션 모니터링을 위해 온라인 평가를 실행합니다.
|
사전 요구 사항
W\&B Skills를 사용하려면 다음이 필요합니다.
* `npx` 명령을 실행하기 위한 [Node.js](https://nodejs.org/)
* Forge API 키. [forge.coreweave.com/settings#apikeys](https://forge.coreweave.com/settings#apikeys)에서 API 키를 생성한 다음 환경 변수로 설정하세요. `[YOUR-API-KEY]`를 본인의 API 키로 바꾸세요.
```bash theme={"system"}
export WANDB_API_KEY="[YOUR-API-KEY]"
```
* 선택: Weights & Biases 프로젝트 이름을 `WANDB_PROJECT` 환경 변수로 설정하세요. 이렇게 하면 매번 프로젝트를 지정하지 않아도 에이전트가 올바른 Weights & Biases 프로젝트에서 작업할 수 있습니다.
W\&B Skills 설치
모든 프로젝트에서 Skills를 사용하려면 전역 설치를, 특정 프로젝트에서만 Skills를 사용하려면 프로젝트별 설치를 선택하세요.
모든 프로젝트에서 사용할 수 있도록 W\&B Skills를 전역으로 설치하려면 `--global` 플래그를 사용하세요.
```bash theme={"system"}
npx skills add wandb/skills --skill '*' --yes --global
```
현재 프로젝트에만 Skills를 설치하려면 프로젝트 디렉터리에서 `--global` 플래그 없이 설치 명령을 실행하세요.
```bash theme={"system"}
npx skills add wandb/skills --skill '*' --yes
```
`--agent` 플래그를 사용하면 특정 에이전트용 Skills를 설치할 수 있습니다.
```bash theme={"system"}
npx skills add wandb/skills \
--agent claude-code \
--skill '*' \
--yes \
--global
```
`--agent` 및 `--skill` 옵션 목록은 [Vercel Labs skills CLI 문서](https://github.com/vercel-labs/skills#supported-agents)를 참조하세요.
설치가 완료되면 에이전트가 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-server-capabilities) 섹션을 참조하세요.
배포 유형
Weights & Biases MCP 서버는 두 가지 배포 옵션을 제공합니다. 가장 빠르게 설정하려면 호스팅 서버를 사용하고, 더 높은 격리 수준과 유연성이 필요하다면 로컬 버전을 설정하세요. 로컬 버전을 사용하는 경우 클라이언트가 서버에 액세스할 때 다른 URL을 사용해야 합니다.
Weights & Biases가 관리하는 MCP 서버로, 클라이언트가 API 키를 사용해 HTTP로 연결합니다. 별도로 설치하거나 유지 관리할 로컬 프로세스가 없습니다.
[호스팅 서버 사용하기](#use-the-hosted-server)
STDIO 또는 HTTP를 통해 자체 머신에서 MCP 서버를 실행합니다. 에어갭 환경에서 운영해야 하거나, 특정 릴리스로 버전을 고정하거나, 서버 동작을 맞춤형으로 변경하거나, 서버를 직접 개발 중이거나, STDIO만 지원하는 클라이언트를 사용해야 할 때 적합합니다.
[로컬에서 MCP 서버 실행하기](#run-the-mcp-server-locally)
사전 요구 사항
클라이언트를 설정하기 전에 다음 사항이 준비되어 있는지 확인하세요.
* [forge.coreweave.com/settings#apikeys](https://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](https://pypi.org/project/mcp/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 서버를 등록하세요.
```bash theme={"system"}
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`을 호출하여 사용자 이름과 소속 팀을 반환하면 정상입니다. 연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요. 자세한 내용은 [Claude Code의 MCP 문서](https://docs.anthropic.com/en/docs/claude-code/mcp)를 참조하세요.
Claude Desktop의 기본 제공 맞춤형 커넥터 인터페이스는 원격 MCP 서버에 대한 API 키 인증을 지원하지 않습니다. 이 제한을 우회하려면 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) npm 프록시를 사용하여 Claude Desktop을 Weights & Biases 원격 MCP 서버에 연결하세요. 이 프록시는 로컬에서 실행되며, 요청을 Bearer 토큰과 함께 `https://mcp.withwandb.com/mcp`로 전달합니다.
시스템에 [Node.js](https://nodejs.org/)가 설치되어 있어야 합니다.
텍스트 편집기에서 Claude Desktop 설정 파일을 여세요. 운영 체제별 설정 파일 위치는 다음과 같습니다.
* **macOS**: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
설정 파일의 JSON 객체에 다음 내용을 추가하고, `[YOUR-WANDB-API-KEY]`를 본인의 API 키로 바꾸세요.
```json theme={"system"}
{
"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`을 호출하여 사용자 이름과 소속된 팀을 반환하면 정상입니다. 연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요.
API 키를 환경 변수로 내보낸 다음 Codex에 서버를 등록하세요.
```bash theme={"system"}
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`을 호출하고 사용자 이름과 소속된 팀을 반환하면 정상입니다. 연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요.
[원클릭 설치 링크](https://cursor.com/en/install-mcp?name=wandb\&config=eyJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3Aud2l0aHdhbmRiLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIge3tXQU5EQl9BUElfS0VZfX0iLCJBY2NlcHQiOiJhcHBsaWNhdGlvbi9qc29uLCB0ZXh0L2V2ZW50LXN0cmVhbSJ9fQ%3D%3D)로 Cursor에 서버를 자동 설치한 다음, `Authorization` 필드의 플레이스홀더를 본인의 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` 객체에 다음 내용을 추가하세요.
```json theme={"system"}
{
"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`을 호출하여 사용자 이름과 소속된 팀을 반환하면 정상입니다.
연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요. 자세한 내용은 [Cursor MCP 문서](https://cursor.com/docs/context/mcp)를 참조하세요.
Weights & Biases MCP 확장을 설치하세요.
```bash theme={"system"}
gemini extensions install https://github.com/wandb/wandb-mcp-server
```
Gemini CLI를 다시 시작하세요. `List my W&B entities.`라고 요청하여 연결을 확인하세요. 에이전트가 `list_entities_tool`을 호출하여 사용자 이름과 소속된 모든 팀을 반환하면 정상입니다.
연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요. 자세한 내용은 [Gemini CLI MCP 문서](https://geminicli.com/docs/tools/mcp-server/)를 참조하세요.
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**: 본인의 API 키
4. **Create**를 선택하세요.
5. `List my W&B entities.`라고 질문하여 연결을 확인하세요. 에이전트가 `list_entities_tool`을 호출하여 사용자 이름과 소속된 모든 팀을 반환하면 정상입니다.
연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요. 자세한 내용은 [LeChat의 MCP 문서](https://mistral.ai/news/le-chat-mcp-connectors-memories)를 참조하세요.
OpenAI Responses API 호출 시 `tools` 필드에 서버를 추가하세요:
```python theme={"system"}
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 서버를 로컬에서 실행하기](#run-the-mcp-server-locally)를 참조하세요.
전역 또는 워크스페이스의 `mcp.json`(예: `~/.vscode/mcp.json` 또는 `.vscode/mcp.json`) 파일을 열고 다음 내용을 추가하세요.
```json theme={"system"}
{
"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`을 호출하여 사용자 이름과 소속된 팀을 반환하면 정상입니다.
연결에 실패하면 [문제 해결](#troubleshooting)을 참조하세요.
MCP 서버를 로컬에서 실행
로컬 설치는 호스팅 서버를 대신하는 선택지이며, 어떤 배포 유형에서도 기본 방식이 아닙니다. 호스팅 서버가 현재 설정에 맞지 않을 때 로컬 설치를 사용하세요.
로컬에서 실행하는 일반적인 이유는 다음과 같습니다.
* **에어갭 또는 오프라인 환경**: 클라이언트가 호스팅된 Weights & Biases 엔드포인트에 연결할 수 없는 경우
* **버전 고정**: 호스팅 서버는 main 브랜치를 따르지만, 로컬 설치에서는 특정 릴리스 태그로 버전을 고정할 수 있습니다.
* **맞춤형 서버 동작**: 도구 설명 변경, 도구 추가, 기본값이 아닌 응답 토큰 예산 설정 등
* **서버 자체 개발**: 서버를 직접 개발하고 있는 경우
* **STDIO 전용 클라이언트** 또는 로컬 프로세스가 필요한 클라이언트
Dedicated Cloud 또는 Self-Managed 사용자는 호스팅 방식을 우선 사용하세요. 인스턴스에서 호스팅 서버가 아직 활성화되지 않았거나 앞서 설명한 이유 중 하나에 해당하는 경우에만 [wandb/wandb-mcp-server](https://github.com/wandb/wandb-mcp-server)를 로컬에 설치해 사용하세요. 이때 `WANDB_BASE_URL` 환경 변수를 인스턴스 URL로 설정하세요.
로컬 사전 요구 사항
서버를 로컬에서 실행하려면 다음 항목이 준비되어 있는지 확인하세요.
* Python 3.11 이상
* [`uv`](https://docs.astral.sh/uv/) 또는 `pip`
* `WANDB_API_KEY`에 설정된 API 키
* Dedicated Cloud 또는 Self-Managed를 사용하는 경우, 인스턴스 URL로 설정된 `WANDB_BASE_URL`
서버 설치
설치 방법을 선택한 다음 아래 명령을 실행하여 MCP 서버를 설치하세요.
```bash theme={"system"}
uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server
```
```bash theme={"system"}
uv pip install wandb-mcp-server
```
```bash theme={"system"}
pip install wandb-mcp-server
```
```bash theme={"system"}
pip install git+https://github.com/wandb/wandb-mcp-server
```
서버를 설치했으면 서버를 실행하도록 클라이언트를 설정하세요. 사용하는 MCP 클라이언트를 선택한 다음 아래 설정을 실행하고, 필요한 경우 `[YOUR-WANDB-API-KEY]`를 본인의 API 키로 바꾸세요.
로컬 서버를 Claude Code에 등록하세요. 전역으로 설정하려면 `--scope user`를 추가하세요.
```bash theme={"system"}
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`의 전체 경로를 사용하세요.
```json theme={"system"}
{
"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을 다시 시작하면 설정이 적용됩니다.
```bash theme={"system"}
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` 설정에 다음 내용을 추가하세요.
```json theme={"system"}
{
"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 설정에 다음 내용을 추가하세요.
```json theme={"system"}
{
"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 전송 방식으로 서버를 실행하세요.
```bash theme={"system"}
uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 8080
```
OpenAI Responses API와 같은 외부 클라이언트에서 로컬 서버에 접근할 수 있도록 하려면 터널을 사용하세요.
```bash theme={"system"}
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](https://github.com/wandb/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](/ko/forge-home)의 프록시 역할을 합니다. | "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](#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 분류](#triage-failing-llm-calls)를 참조하세요.
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 진단하기](#diagnose-a-bad-training-run) 및 [평가 요약 및 모델 버전 비교하기](#summarize-evals-and-compare-model-versions)를 참조하세요.
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 요청 속도 제한](/ko/products/wandb/platform/hosting/hosting-options/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. `list_entities_tool`로 entity 또는 팀을 찾습니다.
2. `query_wandb_entity_projects`로 프로젝트를 찾습니다.
3. run 기반 프로젝트라면 `probe_project_tool`을, Weave 트레이스 프로젝트라면 `infer_trace_schema_tool`을 사용합니다.
4. 앞 단계에서 확인한 키를 사용해 `query_wandb_tool` 또는 `query_weave_traces_tool`을 호출하여 필요한 데이터만 조회합니다.
실패한 LLM Call 분류
문제가 있는 트레이스와 이를 생성한 세션을 찾으려면 다음 도구를 순서대로 연결해 사용하세요.
1. 오류 또는 예외 필드에 대한 필터와 `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`로 손실 곡선과 검증 곡선을 가져옵니다.
2. `diagnose_run_tool`로 수렴, 과적합, NaN 여부를 자동으로 검사합니다.
3. `compare_runs_tool`로 정상 동작이 확인된 기준 run과 비교합니다.
4. `create_wandb_report_tool`로 선 플롯 패널이 포함된 리포트를 만들어 진단 결과를 공유합니다.
평가 요약 및 모델 버전 비교
평가에서 가장 성능이 좋았던 모델 버전을 찾으려면 다음 도구를 차례로 연결해 사용하세요.
1. `summarize_evaluation_tool`: Scorer별 통과율과 오류 수를 확인합니다.
2. `list_artifact_versions_tool`: 해당 모델 컬렉션의 버전 목록을 조회합니다.
3. `compare_artifact_versions_tool`: 후보 버전과 현재 프로덕션 버전을 비교합니다.
4. `log_analysis_to_wandb` 및 `create_wandb_report_tool`: 비교 결과를 게시합니다.
문제 해결
다음 표를 참고하여 Weights & Biases MCP 서버 사용 시 발생하는 문제를 진단하고 해결하세요.
| 증상 | 원인 및 해결 방법 |
| - | - |
| `401 Unauthorized` 또는 `Invalid API key` | API 키가 없거나, 형식이 잘못되었거나, 대상 entity 또는 팀에 대한 권한이 없습니다. [forge.coreweave.com/settings#apikeys](https://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 지원팀](mailto:forge-support@coreweave.com)에 문의하여 활성화를 요청한 다음, [연결 URL](#connection-url)에서 URL을 확인하세요. |
| Dedicated Cloud에서 `429 Too Many Requests` 발생 | 인스턴스의 요청 속도 제한에 도달했습니다. 한도 상향을 요청하는 방법은 [Dedicated Cloud 요청 속도 제한](/ko/products/wandb/platform/hosting/hosting-options/dedicated-cloud/rate-limits)을 참조하세요. |
| Claude Desktop에서 로컬 서버가 `uvx`를 찾지 못함 | `claude_desktop_config.json`의 `command` 필드에 `uvx`의 전체 경로를 입력하세요. |