Skip to content
Navo24Navo24
무료로 시작하기

핵심 개념

MCP 빠른 시작

물류 MCP 서버 빠른 시작: Claude, Cursor 등 MCP 클라이언트를 Navo24에 연결하면 모델이 직접 컨테이너를 추적하고 선박 일정을 비교합니다.

Model Context Protocol을 사용하면 어시스턴트가 도구를 직접 호출할 수 있습니다. Navo24는 제품마다 물류 MCP 서버를 운영하므로, 연동 코드를 작성하지 않아도 모델이 컨테이너를 추적하고 선박 일정을 비교하거나 적재를 계획할 수 있습니다.

서버 목록

제품서버Endpoint전송 방식
TrackingMCPcontainer-trackinghttps://mcp.trackingmcp.com/mcpStreamable HTTP
SchedulesMCPocean-scheduleshttps://mcp.schedulesmcp.com/mcpStreamable HTTP
LoadingMCPcontainer-loadinghttps://mcp.loadingmcp.com/mcpStreamable HTTP
AirCargoMCPair-cargohttps://mcp.aircargomcp.com/mcpStreamable HTTP
FreightRatesMCPfreight-rateshttps://mcp.freightratesmcp.com/mcpStreamable HTTP

AirCargoMCP에서 resolve_awb_prefix는 키 없이도 응답합니다. track_awb와 air_rate_quote에는 tmcp_ 계열 키가 필요합니다.

Claude Desktop과 Cursor

클라이언트 설정에 서버를 추가하세요. Streamable HTTP 서버라면 endpoint와 키를 bearer 헤더로 전달합니다.

{
  "mcpServers": {
    "container-tracking": {
      "url": "https://mcp.trackingmcp.com/mcp",
      "headers": { "Authorization": "Bearer tmcp_YOUR_API_KEY" }
    }
  }
}

로컬 명령만 실행할 수 있는 클라이언트도 mcp-remote를 통해 이 서버들 중 어디에나 연결할 수 있습니다. 항공 화물의 예:

{
  "mcpServers": {
    "air-cargo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.aircargomcp.com/mcp",
               "--header", "Authorization: Bearer tmcp_YOUR_API_KEY"]
    }
  }
}

클라이언트를 다시 시작하면 도구가 나타납니다. 컨테이너 추적을 요청하면 모델이 알아서 get_container_detail을 호출합니다.

모델이 호출할 수 있는 것

각 서버는 REST API와 같은 기능을 도구 형태로 제공합니다. Tracking에는 add_container, get_container_detail, get_shipment_summary 등이 있습니다. Schedules에는 find_best_sailings, carrier_reliability, port_congestion이 있습니다. 전체 도구 목록은 각 제품의 레퍼런스 페이지에 있습니다.

같은 키, 같은 데이터

MCP 도구 호출과 REST 호출은 같은 키로 같은 백엔드에 도달합니다. 모델이 작업을 이끌 때는 MCP를, 자체 코드가 이끌 때는 REST를 쓰세요.

Navo Tokens(Navo 제품들이 함께 쓰는 하나의 선불 잔액)를 보유한 계정에서는 MCP 호출 요금이 이 잔액에서 차감됩니다. 잔액을 나타내는 JSON 필드는 기존의 credits_ 이름을 그대로 유지합니다.

하나의 잔액으로 MCP를 통해 모든 Navo 서비스를 이용할 수 있습니다: TrackingMCP, AirCargoMCP, FreightRatesMCP, SchedulesMCP, LoadingMCP. 제품마다 MCP 접근 권한을 따로 받을 필요가 없습니다. 다만 두 가지 경우에는 여전히 호출이 거부됩니다. 계정 담당자가 고객님 계정에서 닫은 제품, 그리고 범위 설정상 해당 제품이 제외된 키입니다(아래 “제품별 접근 권한” 참고).

MCP 사용량과 API 사용량은 따로 집계됩니다. MCP 호출은 API 키의 월간 호출 한도를 소모하지 않으며, API 키로 하는 REST 호출은 Navo Tokens를 소모하지 않습니다.

호출Tokens
새 컨테이너, 선하증권 또는 부킹 추적250
추적 중인 화물 새로 고침 또는 조회참조 번호당 10
새 항공 운송장 추적200
항공 운송장 새로 고침10
항구 쌍의 운임100, 24시간 내 같은 항구 쌍을 다시 조회하면 10
항구 쌍의 선박 일정80, 24시간 내 같은 항구 쌍을 다시 조회하면 10
새 3D 적재 계획50, 재계산마다 10
항만 혼잡도10
일정 신뢰도, 선사의 항차10
알림 및 webhook무료

여러 참조 번호를 받는 도구는 제출한 고유 참조 번호마다 한 번씩 과금됩니다. 부킹이나 선하증권은 포함된 모든 컨테이너에 대해 한 번만 과금됩니다. 결과가 비어 있으면 무료이고, 거부된 호출에는 아무것도 청구되지 않습니다. 패키지와 가격은 요금 페이지에서 확인하세요.

잔액이 부족할 때

호출이 거부되며, 요금이 청구되지 않고 데이터도 반환되지 않습니다. 코드는 제품마다 다릅니다.

제품거부 응답
TrackingMCP402 INSUFFICIENT_CREDITS
AirCargoMCP402, 코드 insufficient_balance(또는 trial_expired, wallet_inactive, no_wallet)
FreightRatesMCP402, 코드 insufficient_credits(또는 trial_expired, wallet_inactive, no_wallet)
SchedulesMCP데이터를 읽기 전에는 429 QUOTA_EXCEEDED, 응답이 준비된 시점에 잔액으로 더 이상 지불할 수 없으면 402 INSUFFICIENT_CREDITS
LoadingMCP402 INSUFFICIENT_CREDITS, 계획을 계산하기 전에 거부

모든 제품에서 error 객체에는 code와 message 외에 동일한 네 개의 선택 필드가 들어 있습니다.

필드타입내용
credits_requiredinteger 또는 null이 호출에 필요한 tokens. 가격을 알 수 없으면 null.
credits_balanceinteger 또는 null현재 잔액의 tokens. 계정에 아직 잔액이 없으면 null.
top_up_urlstring 또는 null계정 설정의 Billing 페이지로, 여기서 tokens를 추가 구매할 수 있습니다. 링크를 제공할 수 없으면 null.
packages{ plan, credits, usd } 배열구매 가능한 패키지: Starter 7,000 tokens $69, Growth 40,000 tokens $349, Scale 200,000 tokens $1,399.
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough Navo Tokens: this needs 10, your balance is 4. Buy more tokens: https://app.trackingmcp.com/settings?tab=billing&buy=credits (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399).",
    "severity": "warning",
    "credits_required": 10,
    "credits_balance": 4,
    "top_up_url": "https://app.trackingmcp.com/settings?tab=billing&buy=credits",
    "packages": [
      { "plan": "starter", "credits": 7000, "usd": 69 },
      { "plan": "growth", "credits": 40000, "usd": 349 },
      { "plan": "scale", "credits": 200000, "usd": 1399 }
    ]
  }
}

이 필드들은 추가되는 선택 항목입니다. 분기는 계속 code로 처리하고, 필드가 있을 때 읽으세요. 모든 Navo MCP 서버는 이 필드들을 사용자에게 그대로 보여 줄 수 있는 같은 문장으로 바꿉니다: “Not enough Navo Tokens: this needs 10, your balance is 4. Buy more tokens: <link> (Starter 7,000 tokens for $69, Growth 40,000 tokens for $349, Scale 200,000 tokens for $1,399).” 자세한 내용은 각 제품 레퍼런스 페이지의 Navo Tokens 항목에 있습니다.

제품별 접근 권한

Navo Tokens에는 제품별 MCP 접근 권한이 필요하지 않습니다. 계정 담당자가 고객님 계정에서 닫은 제품은 Navo Tokens로도 닫힌 상태로 유지됩니다. 예를 들어 SchedulesMCP에서는 “Ship Schedules is not enabled for MCP on this account. Ask your account manager.”가 반환됩니다. 범위 설정상 해당 제품이 제외된 키는 403으로 거부됩니다. 예를 들어 SchedulesMCP에서는 “Ship Schedules is not enabled for this API key.”, FreightRatesMCP에서는 “Freight Rates is not enabled for this API key. Contact your account manager to open it.”가 반환됩니다.