MCP Server

MCP란

Model Context Protocol(MCP)은 AI 클라이언트가 외부 도구를 표준화된 방식으로 호출하게 해주는 프로토콜입니다. core.today MCP 서버는 모델 검색부터 예측 생성·폴링까지 REST API와 동일한 크레딧 차감·사용량 기록 경로를 그대로 재사용합니다.

인증

두 헤더 중 하나로 인증합니다 — 기능 차이는 없습니다.

X-API-Key: cdt_your_api_key

Authorization: Bearer cdt_your_api_key

연결 확인

설치 후 Claude 등 클라이언트에게 이렇게 말해보세요: "내 core.today 잔액 알려줘" — get_balance는 무료·읽기전용이라 즉시 응답하며, 이 한마디로 인증이 끝까지 통했는지 바로 확인됩니다.

클라이언트 없이 직접 확인하려면 아래처럼 tools/call을 curl로 호출할 수 있습니다.

curl -X POST https://api.core.today/v1/mcp \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_balance", "arguments": {} }
  }'

도구 레퍼런스

9개 도구는 모두 팀의 API 키 권한 범위 안에서 동작합니다. cost 배지는 무엇이 소비되는지를 나타냅니다 — 크레딧 차감, 스토리지 쿼터만 소비, 또는 아무것도 소비하지 않음(레이트리밋만 적용).

워크플로 예제

일반적인 생성 흐름은 검색 → 스키마 확인 → 비용 미리보기 → 생성 → 폴링 순서입니다.

1. search_models로 조건에 맞는 모델을 찾습니다.
2. get_model_schema로 입력 스키마와 정확한 가격을 확인합니다.
3. estimate_credits로 실행 전 예상 크레딧 비용을 미리 봅니다(부작용 없음).
4. create_prediction으로 작업을 시작합니다 — 이 시점에 크레딧이 선차감되며 job_id를 반환합니다.
5. get_prediction(job_id)을 2~5초 간격으로 폴링해 completed/failed/canceled 중 하나가 될 때까지 확인합니다.

// 1) search_models
search_models({ query: "product photo background removal" })

// 2) get_model_schema — inspect the chosen model's input schema
get_model_schema({ model_id: "<chosen model_id>" })

// 3) estimate_credits — preview cost, no side effects
estimate_credits({ model: "<chosen model_id>", input: { ... } })

// 4) create_prediction — spends credits, returns job_id
create_prediction({ model: "<chosen model_id>", input: { ... } })
// → { "job_id": "job_xxx", "status": "processing", ... }

// 5) get_prediction — poll every 2-5s until terminal status
get_prediction({ job_id: "job_xxx" })
// → { "status": "completed", "output_files": [ { "object_key": "...", "url": "..." } ] }

파일 입력 선택 가이드

모델 입력에 파일이 필요하면 상황에 맞는 방법을 고르세요.

에러 코드

도구 호출이 실패하면 ToolError 메시지가 "code: message" 형식으로 반환됩니다. 에이전트는 콜론 앞의 code로 분기해야 합니다 — message는 사람이 읽기 위한 설명으로 문구가 바뀔 수 있습니다.

insufficient_credits: Required 12.50, available 3.20
rate_limited: per_minute limit reached (60/window). Retry after 42s.
not_found: model 'xyz/bad-model' not found. Try search_models first.
validation_error: input.prompt: field required
internal_error: unexpected server error (logged)

제한사항

• 레이트리밋: 읽기 전용 도구(search_models, get_prediction 등)는 호출 1건이 API 키의 분당 예산 1단위를 소비합니다. create_prediction은 예측 경로 자체에서 이미 레이트리밋을 수행하므로 게이트에서 별도로 계수하지 않습니다 — 이중 차감이 없습니다. initialize/tools/list 핸드셰이크는 과금되지 않습니다.
• 세션리스: 서버는 세션 상태를 두지 않는 Streamable HTTP로 동작합니다(ALB 뒤 여러 ECS 태스크 중 아무 곳이나 응답 가능). GET 요청은 지원하지 않으며 405를 반환합니다 — POST/DELETE만 허용됩니다.
• 출력 URL 만료: create_prediction·get_prediction이 반환하는 output_files의 url은 서명된 임시 URL로 만료됩니다. object_key가 영속 식별자이므로 이를 저장해두고 필요할 때 다시 서명하세요.
• import_file_from_url 제한: 파일 크기는 50MB로 제한되며, 사설망·내부 주소(SSRF 방지)는 차단됩니다.
• LLM 채팅: 채팅형 LLM 호출(OpenAI/Anthropic 호환)은 MCP 도구가 아니라 별도의 LLM 게이트웨이(/llm/openai/v1, /llm/anthropic/v1)를 통해 이루어집니다.