가이드

MCP 서버

Weighter MCP 서버는 Agent API를 Claude Desktop·Claude Code 등 LLM 에이전트에 도구(tool)로 노출합니다.

개요

MCP 서버는 두 가지 전송을 지원합니다. 로컬 클라이언트용 stdio와 원격 클라이언트용 Streamable HTTP입니다. HTTP는 기본적으로 루프백에 바인딩되고 Host·Origin 헤더를 검증해 DNS 리바인딩 공격을 방지합니다.

사전 준비

Node.js 22 이상과 발급한 에이전트 키(wtr_ak_...)가 필요합니다.services/mcp에서 npm install && npm run build로 dist/를 생성하세요.

Claude Desktop 등록

claude_desktop_config.json(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\\Claude\\)에 다음을 추가합니다.

claude_desktop_config.json

{
  "mcpServers": {
    "weighter": {
      "command": "node",
      "args": ["/absolute/path/to/services/mcp/dist/index.js"],
      "env": {
        "WEIGHTER_API_URL": "https://api.weighter.shop",
        "WEIGHTER_API_KEY": "wtr_ak_your_key_here"
      }
    }
  }
}

Claude Code 등록

claude mcp add

claude mcp add weighter \
  --env WEIGHTER_API_URL=https://api.weighter.shop \
  --env WEIGHTER_API_KEY=wtr_ak_your_key_here \
  -- node /absolute/path/to/services/mcp/dist/index.js

또는 프로젝트의 .mcp.json에 위 Claude Desktop 예시와 동일한 mcpServers 블록을 추가합니다.

환경 변수

변수	필수	설명
WEIGHTER_API_URL	필수	백엔드 오리진. 서버가 <URL>/agent/v1/... 로 호출합니다.
WEIGHTER_API_KEY	필수	에이전트 키(wtr_ak_...). Bearer 헤더로 전송되며 메모리에만 보관됩니다.
MCP_TRANSPORT	선택	stdio(기본) 또는 http.
MCP_HTTP_HOST	선택	HTTP 전송 바인드 주소(기본 127.0.0.1).
MCP_HTTP_PORT	선택	HTTP 전송 포트(기본 3399).

키 보안

API 키는 로그·도구 응답·오류 메시지에 절대 노출되지 않도록 설계되어 있으며 메모리에만 보관됩니다. 설정 파일에 실제 키를 넣을 때 저장소에 커밋하지 마세요.

제공 도구

도구	권한	설명
weighter_get_station	read	키에 바인딩된 계량소와 요금 규칙 조회.
weighter_list_weighing_records	read	계량 기록 목록 조회(날짜·상태·차량번호·품목 필터).
weighter_get_weighing_record	read	단일 계량 기록(측정값·순중량 포함) 조회.
weighter_create_weighing_record	write	계량소에 새 계량 기록 생성.
weighter_list_certificates	read	증명서 목록 조회(기록·상태 필터).
weighter_send_certificate	write	기존 증명서를 이메일로 발송.
weighter_list_payments	read	결제·미수금 내역 조회(상태·기간 필터).

도구가 호출하는 실제 엔드포인트는 API 레퍼런스에서, 오류 코드는 에러 코드에서 확인하세요.