MCP 서버

API 키로 Claude Code, Cursor, Codex, VS Code 등의 MCP 클라이언트를 SeedRouter의 이미지 및 동영상 모델에 연결합니다.

SeedRouter는 원격 Model Context Protocol 서버를 운영합니다. AI 에이전트는 이 서버를 통해 이미지 및 동영상 모델 목록을 조회하고, 요청 스키마와 요금을 확인하고, 생성 작업을 제출하고, 결과를 가져올 수 있습니다. 직접 연동 코드를 작성할 필요가 없습니다.

https://api.seedrouter.ai/v1/mcp

전송 방식: Streamable HTTP, 무상태입니다. 서버는 프로토콜 버전 2026-07-28과 initialize 핸드셰이크로 시작하는 이전 버전들을 2024-11-05까지 지원합니다.
인증: SeedRouter API 키를 Bearer 토큰으로 사용합니다: Authorization: Bearer YOUR_API_KEY. API 키 페이지에서 생성하세요. 자세한 내용은 인증을 참고하세요.
과금: HTTP API와 같습니다. submit_task 호출은 매번 해당 작업 엔드포인트에 대한 요청 한 건이며, 동일한 방식으로 과금됩니다.

OAuth 로그인만 지원하고 사용자 지정 헤더를 입력할 수 없는 클라이언트는 아직 연결할 수 없습니다.

클라이언트 연결

API 키 페이지의 MCP로 연결 버튼을 사용하면 아래 각 클라이언트의 설정에 보유한 키 중 하나를 채울 수 있습니다.

Claude Code

claude mcp add --transport http seedrouter https://api.seedrouter.ai/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

~/.cursor/mcp.json 또는 프로젝트의 .cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "seedrouter": {
      "url": "https://api.seedrouter.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Codex CLI

Codex는 환경 변수에서 키를 읽습니다:

export SEEDROUTER_API_KEY=YOUR_API_KEY
codex mcp add seedrouter --url https://api.seedrouter.ai/v1/mcp \
  --bearer-token-env-var SEEDROUTER_API_KEY

Codex는 키가 아닌 변수 이름을 저장합니다. SEEDROUTER_API_KEY가 설정된 셸에서 Codex를 시작하세요. 예를 들어 셸 프로필에서 이 변수를 내보내도록 설정할 수 있습니다.

VS Code

.vscode/mcp.json에 추가하세요:

{
  "servers": {
    "seedrouter": {
      "type": "http",
      "url": "https://api.seedrouter.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

사용자 지정 Authorization 헤더로 원격 Streamable HTTP 서버에 연결할 수 있는 다른 클라이언트도 같은 방식으로 설정합니다.

도구

도구	기능	잔액 차감
`list_models`	`submit_task`가 허용하는 모델 ID 목록과 각 모델의 문서 링크를 반환합니다. 선택 사항인 `endpoint`는 `images` 또는 `videos`로 지정합니다.	없음
`get_model_schema`	모델의 요청 본문에 대한 JSON Schema를 반환합니다. 조건부 필수 항목이나 필드 간 제한처럼 JSON Schema로 표현할 수 없는 규칙은 API에서 적용하며, 모델의 문서 페이지에 설명되어 있습니다.	없음
`get_pricing`	과금에 쓰이는 것과 동일한 실시간 요금을 기준으로 모델의 현재 정가를 USD로 반환합니다. 모델 요금 등급이 있으면 해당 요금도 포함합니다.	없음
`submit_task`	작업 한 건을 제출합니다. `model`과 함께 `get_model_schema`가 설명하는 요청 본문인 `input`을 지정합니다. 작업 ID를 반환합니다.	있음, 작업이 생성되는 호출마다 차감
`get_task`	작업의 상태와 출력을 반환합니다. 선택 사항인 `wait_seconds`(0~50)를 지정하면 작업이 실행 중인 동안 서버에서 대기합니다.	없음
`get_balance`	키를 소유한 계정의 남은 잔액을 USD로 반환합니다.	없음

submit_task는 멱등하지 않습니다. 호출을 재시도하면 두 번째 작업이 생성되고 그 비용도 차감됩니다. 결과를 받지 못한 호출을 재시도하기 전에 get_task, get_balance 또는 작업 내역을 확인하세요.

일반적인 흐름

endpoint: "images"로 list_models를 호출합니다.
선택한 모델의 get_model_schema를 호출합니다.
필요하면 먼저 get_pricing으로 요금을 확인합니다.
model과 스키마에 맞는 input으로 submit_task를 호출합니다.
wait_seconds: 50으로 get_task를 호출하고, status가 processing인 동안 반복한 뒤 output을 읽습니다. Seedance 작업은 succeeded 전에 queued와 running 상태를 보고합니다.

생성은 HTTP API와 마찬가지로 비동기 방식입니다. submit_task는 작업이 접수되면 즉시 반환합니다. wait_seconds를 사용하면 에이전트가 반복문으로 폴링할 필요가 없지만, 긴 동영상은 여전히 get_task를 여러 번 호출해야 할 수 있습니다. 대기 중에 요청 수 제한이나 서버 오류 같은 일시적인 이유로 상태 조회가 실패하면, get_task는 오류 대신 마지막 processing 결과를 반환합니다. 다시 호출하세요.

HTTP API와 공통으로 적용되는 규칙

참조 이미지, 동영상, 오디오는 공개 http(s) URL이어야 합니다. Base64 입력은 거부됩니다.
HTTP API가 응답하면 응답 본문이 그대로 도구 결과가 되며, 오류 코드도 동일합니다. 알 수 없는 모델이나 잘못된 도구 인자처럼 요청이 HTTP API에 도달하기 전에 발생하는 오류는 일반 오류 메시지로 반환됩니다. MCP 엔드포인트 자체에서 키가 거부되면 HTTP 401이 반환됩니다.
실패한 작업은 과금되지 않습니다.
기본적으로 계정당 이미지 및 동영상 작업을 최대 50개까지 동시에 실행할 수 있습니다. 실행 중인 작업이 끝날 때까지 추가 제출은 HTTP 429와 코드 30002를 반환합니다. AI 에이전트에서 SeedRouter 사용을 참고하세요.
모델 ID와 파라미터는 각 모델의 문서에 나와 있는 것을 사용합니다. 모델은 API에서 사용할 수 있게 되면 list_models에 표시됩니다.
MCP에서는 텍스트 모델을 제공하지 않습니다. 텍스트 엔드포인트로 호출하거나, SeedRouter에서 코딩 에이전트 사용의 설명에 따라 텍스트 모델로 코딩 에이전트를 실행하세요.

On this page