Tovanix
Tovanix

MCP 연동

Tovanix 계정을 MCP를 지원하는 AI 클라이언트에 연결합니다. 연결 주소는 https://tovanix.com/api/mcp/rpc이며, 세션 없는 Streamable HTTP로 POST만 받습니다.

  • 인증: Authorization: Bearer <자격 증명> 또는 X-MCP-Key 헤더. 자격 증명은 mcp_live_로 시작하며 한 번만 표시됩니다
  • 권한: 모든 기능은 꺼진 상태에서 시작해 하나씩 켭니다. tools/list는 켠 기능만 반환하며, 도구 이름은 tovanix_ 뒤에 기능 이름을 붙인 형태입니다
  • 과금과 되돌릴 수 없는 도구에는 totp_code 일회용 코드가 필요하고 1회·1일 한도가 적용됩니다
  • 접속 IP 허용 목록, 유효 기간, 기본 분당 120회(최대 600회) 호출 제한
  • 리소스 3개(기능 목록, 계정 개요, 이용 안내)와 프롬프트 3개(계정 점검, 지출 보고서, 만료 점검)
  • 오류: 401 자격 증명 무효, 403 접속 위치 또는 계정 상태 불허, 405 POST 아님, 413 요청이 너무 큼
  • 자격 증명을 만들기 전에 「MCP 연동 서비스 약관」에 동의해야 하며, 고객님 명의로 보낸 내용과 작업의 책임은 고객님에게 있습니다
  • 과금과 되돌릴 수 없는 작업 외에도 콜백 URL 변경, 공개 게시, 버킷 공개 접근 같은 중요한 설정에는 일회용 인증 코드가 필요합니다. AI의 게시, 상담원 메시지, 메일 발송, Telegram 실시간 조회에는 계정 단위 빈도 제한이 있고 게시글과 상담원 메시지는 중복 내용이 거부되며, 상담원 메시지에는 ‘AI 어시스턴트가 보냄’이 표시됩니다

POST /api/mcp/rpc

세 가지 자격 증명은 서로 독립적

MCP(Model Context Protocol)를 사용하면 Claude 같은 AI 클라이언트가 Tovanix 계정의 기능을 ‘도구’로 호출할 수 있습니다. 콘솔에서 클라이언트마다 MCP 자격 증명을 만들고, 쓸 수 있는 기능을 하나씩 켭니다. 클라이언트는 그 자격 증명으로 연결 주소에 접속해 대화 안에서 데이터를 조회하고 업무를 처리합니다.

MCP에는 전용 연결 주소와 자격 증명이 있으며, 오픈 API나 콘솔 로그인과는 독립적입니다. MCP 자격 증명을 삭제해도 운영 중인 오픈 API 연동에는 영향이 없고, 그 반대도 마찬가지입니다.

  • 오픈 API /api/v1/* — API 키(X-API-Key / 서명) — 직접 작성한 프로그램 — 키에 설정한 기능
  • MCP /api/mcp/rpc — MCP 자격 증명(Bearer) — AI 클라이언트 — 없음. 하나씩 켜야 함
  • 콘솔 — 로그인 세션 — 본인 — 계정의 모든 기능

빠른 시작

Streamable HTTP를 지원하고 요청 헤더를 설정할 수 있는 MCP 클라이언트라면 연결할 수 있습니다. 아래에서 사용하는 도구를 고르고 해당 명령이나 설정을 복사하세요.

curl로 tools/list를 직접 호출해도 자격 증명을 확인할 수 있습니다. 서버는 세션을 두지 않으므로 initialize를 먼저 보낼 필요가 없습니다.

플랫폼에는 자격 증명의 해시만 저장되므로 잃어버리면 복구할 수 없습니다. 삭제하고 새로 만드세요. 클라이언트 설정 안에 보관하고, 공개 저장소나 스크린샷, 채팅에 남기지 마세요.

연결 주소와 인증

콘솔의 ‘MCP 연동’ 페이지에 계정에서 쓸 수 있는 연결 주소가 표시되며, 그대로 복사할 수 있습니다.

  • 연결 주소 — 모든 요청을 이 주소 하나로 보냅니다.
  • 전송 방식 — Streamable HTTP, 세션 없음: 요청마다 따로 인증하고 POST만 받으며 Mcp-Session-Id를 발급하지 않습니다. GET과 DELETE는 405를 반환합니다.
  • 인증 — Authorization: Bearer <자격 증명>. 클라이언트가 사용자 지정 헤더만 입력할 수 있고 Authorization은 바꿀 수 없다면 X-MCP-Key: <자격 증명>을 사용하세요.
  • 프로토콜 버전 — 2025-06-18(최신), 2025-03-26, 2024-11-05. 클라이언트가 initialize에서 보낸 버전으로 협상하며, 지원하지 않는 버전은 최신 버전으로 맞춥니다.
  • 메시지 — JSON-RPC 2.0, 요청 본문은 1MB 이하입니다. 구버전 클라이언트의 일괄 요청은 최대 32건입니다.
  • 브라우저 요청 — 플랫폼 자체 사이트가 아닌 Origin 헤더를 가진 요청은 거부됩니다(DNS 리바인딩 방지). 데스크톱과 명령줄 클라이언트는 Origin을 보내지 않으므로 영향이 없습니다.

자격 증명과 권한

자격 증명은 mcp_live_로 시작하는 73자입니다. 자격 증명마다 아래 항목을 따로 설정하며 콘솔에서 언제든 바꿀 수 있습니다. 만료되거나 중지된 자격 증명은 즉시 쓸 수 없게 됩니다.

자격 증명을 만들기 전에 「MCP 연동 서비스 약관」을 읽고 동의해야 합니다. 약관에는 AI가 계정을 조작할 때의 위험과 책임이 적혀 있으며, MCP를 통해 발생한 작업과 손실은 고객님이 부담합니다. 약관이 게시되지 않은 동안에는 자격 증명을 만들 수 없습니다. 약관이 바뀐 뒤 새로 만드는 자격 증명은 다시 동의해야 하며, 기존 자격 증명은 계속 사용할 수 있습니다.

계정이 제한된 동안 MCP는 조회 기능만 허용하며, 쓰기·과금·되돌릴 수 없는 작업은 거부하고 콘솔에서 사유를 확인하도록 안내합니다. 계정이 동결되면 모든 요청이 403을 받습니다.

도구와 이름 규칙

도구 이름 = tovanix_ + 기능 이름(점을 밑줄로 변경). 예를 들어 기능 account.balance.get은 도구 tovanix_account_balance_get이 됩니다.

tools/list는 이 자격 증명에서 켠 기능만 반환합니다. 각 도구 설명에는 언제 쓰는지, 매개변수의 의미, 주의할 점이 적혀 있으며 AI 클라이언트는 이를 보고 도구를 고릅니다.

조회: 읽기 전용. 쓰기: 되돌릴 수 있는 변경(메모 수정 등). 과금: 잔액에서 차감. 되돌릴 수 없음: 실행하면 되돌릴 수 없음(키 삭제, 카드 해지 등). 과금과 되돌릴 수 없는 도구에는 일회용 코드가 필요합니다(다음 절 참고). 또한 되돌릴 수는 있지만 즉시 확인이 필요한 중요한 설정(콜백 URL 변경, 공개 게시, 버킷 공개 접근 등)에도 일회용 인증 코드가 필요합니다. 콘솔에서 기능을 고를 때 이런 항목에는 ‘인증 코드 필요’가 표시됩니다.

일회용 코드

과금과 되돌릴 수 없는 도구에는 totp_code 매개변수가 추가되며, 인증 앱에 표시된 현재 6자리 코드를 넣어야 합니다. AI는 이 코드를 얻을 수 없으므로 필요할 때 사용자에게 요청합니다. ‘인증 코드 필요’가 표시된 도구도 마찬가지입니다.

  • 각 코드는 한 번만 쓸 수 있습니다. 콘솔에서 방금 쓴 코드는 MCP에서도 다시 쓸 수 없습니다.
  • 계정에 2단계 인증이 켜져 있지 않으면 이 도구들은 항상 거부되며, 콘솔에서 켜도록 안내합니다.
  • 코드 확인은 다른 모든 단계보다 먼저 이뤄지므로, 코드를 틀려도 1일 지출 한도가 줄지 않습니다.

지출 한도

과금 호출은 아래 네 단계를 차례로 거치며, 어느 하나라도 통과하지 못하면 돈이 나가지 않습니다.

confirmed_total_usd

대부분의 과금 도구는 confirmed_total_usd를 요구합니다. AI가 사용자에게 알려 주고 사용자가 동의한 총액입니다. 실행 시점의 실제 가격이 이보다 높으면 실행하지 않고, AI가 새 가격을 다시 알려 줍니다.

실패했을 때 한도 처리

실행에 실패했고 청구되지 않은 것이 확실하면 미리 잡아 둔 한도를 돌려줍니다. 청구 결과를 확인할 수 없으면 한도를 유지해, 실제로 발생했을 수 있는 지출이 집계에서 빠지지 않게 합니다. 실제 청구액은 청구 내역에서 확인하세요.

빈도 제한과 대신 보내는 내용

자격 증명별 호출 빈도와 별도로, AI가 내용을 작성하는 기능과 Telegram에 실시간으로 요청하는 기능에는 계정 단위 상한이 있습니다. 같은 계정의 모든 자격 증명이 함께 쓰며 매일 UTC+8 0시에 초기화됩니다. 상한을 넘으면 호출이 거부되고 AI에게 멈추라고 안내합니다. 커뮤니티 글과 상담원 메시지는 10분 안에 완전히 같은 내용을 다시 보내면 거부되고, 메일은 내용이 아니라 idempotency_key로 중복을 막습니다. 콘솔에서 기능을 고를 때 이런 항목에는 ‘빈도 제한’이 표시됩니다.

고객님 명의로 보내는 내용

해당 기능을 켜면 AI가 고객님 명의로 커뮤니티 글 작성과 댓글, 상담원 메시지, SMTP 계정 메일 발송을 할 수 있습니다. 이 내용은 고객님 본인의 것이며 책임도 고객님에게 있습니다.

리소스와 프롬프트

도구 외에도 서버는 읽기 전용 리소스 3개와 프롬프트 3개를 제공하며, 클라이언트에서 바로 쓸 수 있습니다.

  • tovanix://catalog — 기능 목록: 모든 영역과 기능, 그리고 이 자격 증명에서 켠 기능. AI가 ‘권한 없음’을 만나거나 무엇을 할 수 있는지 질문받으면 이것을 읽습니다.
  • tovanix://account/overview — 계정 개요: 계정 상태, 이용 중인 서비스, 이 자격 증명의 권한과 당일 한도 사용 현황. 잔액은 ‘계정 잔액 조회’를 켰을 때만 표시됩니다.
  • tovanix://guide — 플랫폼 이용 안내: 금액과 통화 표기, 주문 상태, 주문 전에 확인할 사항.
  • account_health — — — 계정 점검: 잔액, 서비스별 구독과 만료, 이상 주문을 확인하고 처리할 일을 정리합니다.
  • spend_report — days, 기본값 30 — 지출 보고서: 최근 청구와 지출을 서비스별로 합산합니다.
  • renewal_check — within_days, 기본값 14 — 만료 점검: 곧 만료되는 서비스와 연장 비용을 정리하며, 자동으로 연장하지는 않습니다.

오류와 문제 해결

연결과 인증 문제는 HTTP 상태 코드로 반환됩니다. 업무상 실패는 도구 결과(isError: true)로 반환되며, 본문은 “사용자에게 일회용 코드를 요청하세요”, “잔액이 부족합니다. 먼저 충전하도록 안내하세요”처럼 AI가 다음에 할 일을 알려 줍니다.

AI 도구별 Tovanix MCP 연결 방법

<YOUR_MCP_CREDENTIAL>를 콘솔에서 만든 MCP 자격 증명으로 바꾸세요.

  • Claude Code — 터미널에서 실행
    claude mcp add --scope user --transport http tovanix https://tovanix.com/api/mcp/rpc --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>"
  • Codex — 설정 파일: ~/.codex/config.toml
    [mcp_servers.tovanix]
    url = "https://tovanix.com/api/mcp/rpc"
    bearer_token_env_var = "TOVANIX_MCP_CREDENTIAL"
  • Cursor — 설정 파일: ~/.cursor/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • GitHub Copilot (VS Code) — 설정 파일: .vscode/mcp.json
    {
      "servers": {
        "tovanix": {
          "type": "http",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer ${input:tovanix-credential}"
          }
        }
      },
      "inputs": [
        {
          "type": "promptString",
          "id": "tovanix-credential",
          "description": "Tovanix MCP credential",
          "password": true
        }
      ]
    }
  • Gemini CLI — 설정 파일: ~/.gemini/settings.json
    {
      "mcpServers": {
        "tovanix": {
          "httpUrl": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • OpenCode — 설정 파일: ~/.config/opencode/opencode.json
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "tovanix": {
          "type": "remote",
          "url": "https://tovanix.com/api/mcp/rpc",
          "enabled": true,
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Qwen Code — 터미널에서 실행
    qwen mcp add --scope user --transport http tovanix https://tovanix.com/api/mcp/rpc --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>"
  • Kimi Code CLI — 설정 파일: ~/.kimi-code/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • CodeBuddy Code — 터미널에서 실행
    codebuddy mcp add --scope user --transport http --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>" tovanix https://tovanix.com/api/mcp/rpc
  • Qoder CLI — 설정 파일: ~/.qoder/settings.json
    {
      "mcpServers": {
        "tovanix": {
          "type": "streamable-http",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Kiro — 설정 파일: ~/.kiro/settings/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Trae — 설정 파일: .trae/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Trae CN — 설정 파일: .trae/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Trae CLI — 설정 파일: trae_cli.yaml
    mcp_servers:
      - name: "tovanix"
        url: "https://tovanix.com/api/mcp/rpc"
        type: "http"
        headers:
          Authorization: "Bearer <YOUR_MCP_CREDENTIAL>"
  • GitHub Copilot CLI — 설정 파일: ~/.copilot/mcp-config.json
    {
      "mcpServers": {
        "tovanix": {
          "type": "http",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          },
          "tools": [
            "*"
          ]
        }
      }
    }
  • Cline — 설정 파일: cline_mcp_settings.json
    {
      "mcpServers": {
        "tovanix": {
          "type": "streamableHttp",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Kilo Code — 설정 파일: ~/.config/kilo/kilo.jsonc
    {
      "mcp": {
        "tovanix": {
          "type": "remote",
          "url": "https://tovanix.com/api/mcp/rpc",
          "enabled": true,
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Continue — 설정 파일: ~/.continue/config.yaml
    mcpServers:
      - name: tovanix
        type: streamable-http
        url: https://tovanix.com/api/mcp/rpc
        requestOptions:
          headers:
            Authorization: Bearer <YOUR_MCP_CREDENTIAL>
  • Zed — 설정 파일: ~/.config/zed/settings.json
    {
      "context_servers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Junie — 설정 파일: ~/.junie/mcp/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Amp — 설정 파일: ~/.config/amp/settings.json
    {
      "amp.mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Goose — 설정 파일: ~/.config/goose/config.yaml
    extensions:
      tovanix:
        enabled: true
        type: streamable_http
        name: tovanix
        uri: https://tovanix.com/api/mcp/rpc
        headers:
          Authorization: "Bearer <YOUR_MCP_CREDENTIAL>"
        timeout: 300
  • Augment (Auggie) — 터미널에서 실행
    auggie mcp add tovanix --transport http --url https://tovanix.com/api/mcp/rpc --header "Authorization:Bearer <YOUR_MCP_CREDENTIAL>"
  • Factory Droid — 터미널에서 실행
    droid mcp add tovanix https://tovanix.com/api/mcp/rpc --type http --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>" --no-oauth
  • Crush — 설정 파일: ~/.config/crush/crushrc
    mcp add tovanix --type http --url https://tovanix.com/api/mcp/rpc --header Authorization "Bearer <YOUR_MCP_CREDENTIAL>"
  • Warp — 설정 화면에 붙여 넣기
    {
      "tovanix": {
        "url": "https://tovanix.com/api/mcp/rpc",
        "headers": {
          "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
        }
      }
    }
  • Windsurf — 설정 파일: ~/.codeium/windsurf/mcp_config.json
    {
      "mcpServers": {
        "tovanix": {
          "serverUrl": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Claude(웹 / 데스크톱) — 화면에서 주소를 입력하고 Authorization 헤더(Bearer + 자격 증명)를 추가
    https://tovanix.com/api/mcp/rpc
  • LM Studio — 설정 파일: mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Dify — 화면에서 주소를 입력하고 Authorization 헤더(Bearer + 자격 증명)를 추가
    https://tovanix.com/api/mcp/rpc
  • Coze — 화면에서 주소를 입력하고 Authorization 헤더(Bearer + 자격 증명)를 추가
    https://tovanix.com/api/mcp/rpc
  • n8n — 화면에서 주소를 입력하고 Authorization 헤더(Bearer + 자격 증명)를 추가
    https://tovanix.com/api/mcp/rpc
  • 기타 MCP 지원 도구 — 설정 화면에 붙여 넣기
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }

자주 묻는 질문

tools/list가 빈 목록을 반환하는 이유는?

이 자격 증명에서 아직 켠 기능이 없기 때문입니다. 콘솔의 ‘MCP 연동’에서 필요한 기능을 선택한 뒤 다시 연결하세요.

과금 도구가 계속 거부되는 이유는?

지출 한도가 기본값 0 그대로인지, 2단계 인증이 켜져 있는지, 1일 한도를 다 썼는지 세 가지를 확인하세요.

관련 페이지: AI 어시스턴트에게 Tovanix 계정을 맡기세요 · API 문서 · 개발자 연동

불러오는 중…