MCP 서버

빠른 시작

1. 콘솔의 API 키 페이지에서 API 키를 만드세요. 에이전트용 키에는 지출 한도와 허용 모델 목록을 설정하세요.
2. 아래 스니펫 중 하나로 클라이언트에 서버를 추가하세요. 키는 파일에 붙여 넣지 말고 환경 변수에서 읽도록 하세요.
3. 에이전트에게 이렇게 요청해 보세요: “도구를 지원하는 가장 저렴한 모델 세 개를 나열하고, 그중 가장 빠른 모델에게 이 파일을 요약하게 한 다음, 비용이 얼마였는지 알려줘.”

클라이언트 연결

모든 클라이언트는 같은 엔드포인트와 헤더를 사용합니다. 먼저 환경 변수 SYNTHORAI_API_KEY를 설정하세요.

Claude Code

Claude Code에서 /mcp를 실행해 연결을 확인하세요. --scope user를 추가하면 모든 프로젝트에서 서버를 사용할 수 있고, .mcp.json 형식으로 커밋하면 팀과 공유할 수 있습니다(키는 각 개발자의 환경에만 남습니다).

claude mcp add --transport http synthorai https://synthorai.io/v1/mcp \
  --header "Authorization: Bearer $SYNTHORAI_API_KEY"

{
  "mcpServers": {
    "synthorai": {
      "type": "http",
      "url": "https://synthorai.io/v1/mcp",
      "headers": { "Authorization": "Bearer ${SYNTHORAI_API_KEY}" }
    }
  }
}

Cursor

~/.cursor/mcp.json(모든 프로젝트) 또는 .cursor/mcp.json(단일 프로젝트)에 추가하세요.

{
  "mcpServers": {
    "synthorai": {
      "url": "https://synthorai.io/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:SYNTHORAI_API_KEY}" }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json에 추가하세요. VS Code가 키를 한 번 입력받아 안전하게 저장합니다.

{
  "inputs": [
    { "type": "promptString", "id": "synthorai-key", "description": "Synthorai API key", "password": true }
  ],
  "servers": {
    "synthorai": {
      "type": "http",
      "url": "https://synthorai.io/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:synthorai-key}" }
    }
  }
}

Codex CLI

~/.codex/config.toml에 추가하거나 codex mcp add synthorai --url https://synthorai.io/v1/mcp --bearer-token-env-var SYNTHORAI_API_KEY를 실행하세요.

[mcp_servers.synthorai]
url = "https://synthorai.io/v1/mcp"
bearer_token_env_var = "SYNTHORAI_API_KEY"

OpenAI Responses API

OpenAI 서버가 사용자를 대신해 엔드포인트를 호출하므로 키의 IP 허용 목록은 비워 두세요(또는 OpenAI의 송신 IP 대역을 허용하세요). allowed_tools로 모델에 필요한 도구만 노출하세요.

import os
from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "synthorai",
        "server_url": "https://synthorai.io/v1/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['SYNTHORAI_API_KEY']}"},
        "allowed_tools": ["list_models", "chat_completion"],
        "require_approval": "never",
    }],
    input="Find the cheapest Synthorai chat model with tool support and ask it for a haiku about gateways.",
)
print(resp.output_text)

OpenAI Agents SDK

MCP 클라이언트 SDK 기반의 모든 프레임워크(LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra …)에서도 똑같이 동작합니다. Streamable HTTP 전송이 이 엔드포인트를 가리키도록 하고 헤더를 추가하세요.

import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="synthorai",
        params={
            "url": "https://synthorai.io/v1/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['SYNTHORAI_API_KEY']}"},
            "timeout": 120,
        },
        cache_tools_list=True,
    ) as synthorai:
        agent = Agent(name="assistant", instructions="Use the Synthorai tools.", mcp_servers=[synthorai])
        result = await Runner.run(agent, "List three chat models under $1 per million input tokens.")
        print(result.final_output)

asyncio.run(main())

MCP Python SDK

import asyncio, os, httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    http = httpx2.AsyncClient(
        headers={"Authorization": f"Bearer {os.environ['SYNTHORAI_API_KEY']}"}, timeout=120)
    async with Client(streamable_http_client("https://synthorai.io/v1/mcp", http_client=http)) as mcp:
        tools = await mcp.list_tools()
        print([t.name for t in tools.tools])
        result = await mcp.call_tool("chat_completion",
                                     {"model": "deepseek-v4-flash", "prompt": "Say hi in five words"})
        print(result.content[0].text)

asyncio.run(main())

Claude Desktop

Claude Desktop과 claude.ai의 사용자 지정 커넥터는 OAuth로 로그인하는데, 이 서버는 아직 OAuth를 지원하지 않습니다(아래 향후 계획 참고). 그때까지 Claude Desktop은 헤더를 대신 추가해 주는 mcp-remote 브리지로 연결할 수 있습니다:

{
  "mcpServers": {
    "synthorai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://synthorai.io/v1/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer sk-syn-..." }
    }
  }
}

curl

서버는 HTTP 위의 순수 JSON-RPC이므로 SDK가 필요 없습니다. 핸드셰이크도 필요 없으며, 모든 요청이 독립적으로 처리됩니다.

curl https://synthorai.io/v1/mcp \
  -H "Authorization: Bearer $SYNTHORAI_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":"chat_completion",
                 "arguments":{"model":"deepseek-v4-flash","prompt":"Say hi in five words"}}}'

응답 예시

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Hi there, great to meet!" },
      { "type": "text", "text": "[deepseek-v4-flash · finish_reason stop · 12 in / 7 out tokens · cost $0.0000031 · request_id 0199a7c2-…]" }
    ],
    "structuredContent": {
      "model": "deepseek-v4-flash",
      "content": "Hi there, great to meet!",
      "finish_reason": "stop",
      "usage": { "prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19 },
      "cost_usd": 0.0000031,
      "request_id": "0199a7c2-…"
    }
  }
}

도구

tools/list는 키로 사용할 수 있는 도구만 반환하며, 키 종류와 워크스페이스에서 활성화된 기능에 따라 필터링됩니다(이미지 및 동영상 생성은 제한된 프리뷰로 제공됩니다). 모델을 실행하는 도구의 비용은 REST 호출 비용과 정확히 같고, 그 밖의 도구는 모두 무료입니다.

추론 키

프로비저닝 키

빌링 키

list_models, get_model, get_pricing은 모든 키 종류에서 제공됩니다. 추론 키의 경우 list_models는 해당 키로 호출할 수 있는 모델만 보여 줍니다.

결과 형식

모든 결과에는 읽기 쉬운 텍스트 블록과 함께 같은 데이터를 JSON으로 담은 structuredContent가 포함되므로, 채팅 클라이언트와 프로그램 모두 사용할 수 있습니다. 이미지와 오디오는 이미지 및 오디오 콘텐츠로, 동영상은 링크로 반환됩니다. 모델을 실행하는 도구는 끝에 영수증 줄(모델, 토큰, 비용, request_id)을 붙이며, 나중에 get_generation으로 조회할 수 있습니다.

권한과 보안

• REST API와 동일한 규칙. 각 도구 호출은 해당 도구에 명시된 REST 엔드포인트가 사용자의 키로 수행합니다. 인증, 키 종류, IP 허용 목록, 허용 모델 목록, 지출 한도, 속도 제한, 과금이 모두 그대로 적용됩니다. MCP는 권한을 추가하지도, 검사를 건너뛰지도 않습니다.
• 키 종류별 최소 권한. 추론 키는 키를 관리하거나 워크스페이스 청구 데이터를 읽을 수 없고, 프로비저닝 키는 모델을 호출할 수 없으며, 빌링 키는 읽기 전용입니다.
• 승인 힌트. 모든 도구에는 MCP 어노테이션이 붙어 있습니다. 읽기 전용 도구는 readOnlyHint로 표시되고, 비용이 발생하는 도구는 읽기 전용이 아니며, update_api_key, delete_api_key, cancel_video는 destructiveHint로 표시됩니다. 클라이언트는 이를 바탕으로 실행 전에 무엇을 확인받을지 결정합니다.
• 권장 에이전트 키: 매일 재설정되는 지출 한도와 allowed_models 목록을 설정하고, 에이전트가 알려진 호스트에서 실행된다면 IP 허용 목록까지 지정한 전용 추론 키. 프로덕션 키에 영향을 주지 않고 이 키만 따로 폐기할 수 있습니다.
• 비밀 값과 신뢰할 수 없는 콘텐츠. create_api_key는 새 키를 한 번만 반환하므로 에이전트에게 어디에 저장할지 알려 주세요. 모델 출력과 도구 결과는 신뢰할 수 없는 입력(프롬프트 인젝션)으로 취급한 뒤에 에이전트가 이를 바탕으로 행동하게 하세요.

프로토콜 세부 사항

문제 해결

향후 계획

• OAuth 로그인: claude.ai, Claude Desktop, ChatGPT 커넥터가 키를 붙여 넣지 않고도 지출 한도가 걸린 단기 자격 증명으로 연결할 수 있게 됩니다.
• MCP 게이트웨이: 같은 엔드포인트에서 서드파티 MCP 서버(GitHub, Slack, 직접 운영하는 서버)까지 사용자의 키로 통합하며, 도구별 권한, 서버 측 자격 증명 보관, 단일 감사 로그를 제공합니다.
• 장시간 호출 진행 상황: 도구가 실행되는 동안 진행 상황을 스트리밍합니다.

관련 문서: API 키 · 프로비저닝 키 · 빌링 API · Chat Completions