MCP 서버

빠른 시작

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

클라이언트 연결

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

로그인으로 연결하는 클라이언트(claude.ai, Claude Desktop, ChatGPT)에는 키가 필요 없습니다. 위 엔드포인트를 커넥터로 추가하고 Synthorai에 로그인한 뒤, 워크스페이스와 이 연결에 허용할 작업을 선택하세요. 연결마다 만료일이 있는 전용 키가 발급되며, 'API 키'에 표시되고 언제든 삭제할 수 있습니다.

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은 로그인으로 연결합니다. 엔드포인트를 사용자 지정 커넥터로 추가하면 키가 필요 없습니다. 직접 만든 키를 쓰려면 헤더를 대신 추가해 주는 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는 해당 키로 호출할 수 있는 모델만 보여 줍니다.

연결 권한 제어하기

• 워크스페이스 단위. 관리자는 설정 > MCP에서 MCP를 켜거나 끄고, 연결이 사용할 수 있는 도구 그룹을 고르고, 변경을 일으키는 도구의 사용 여부를 정합니다. 전용 인스턴스에서는 관리자가 켜기 전까지 MCP가 꺼져 있습니다.
• 연결 단위. X-MCP-Readonly: true를 보내면 변경을 일으키거나 비용이 드는 도구가 모두 빠지고, X-MCP-Toolsets: logs,prompts를 보내면 해당 그룹만 남습니다(usage, logs, prompts, keys, workspace, inference). 헤더를 설정할 수 없는 클라이언트는 URL에 ?readonly=true&toolsets=logs,prompts를 붙입니다.
• 이 설정은 모두 도구를 줄이기만 합니다. 키의 스코프, 워크스페이스 설정, 연결에 건 제한이 모두 허용하는 도구만 목록에 나타납니다.
• 모든 변경은 기록됩니다. MCP로 변경한 내용은 사용한 키, 클라이언트 이름과 함께 감사 로그에 남습니다.

결과 형식

모든 결과에는 읽기 쉬운 텍스트 블록과 함께 같은 데이터를 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는 새 키를 한 번만 반환하므로 에이전트에게 어디에 저장할지 알려 주세요. 모델 출력과 도구 결과는 신뢰할 수 없는 입력(프롬프트 인젝션)으로 취급한 뒤에 에이전트가 이를 바탕으로 행동하게 하세요.

프로토콜 세부 사항

문제 해결

향후 계획

• MCP 게이트웨이: 같은 엔드포인트에서 서드파티 MCP 서버(GitHub, Slack, 직접 운영하는 서버)까지 사용자의 키로 통합하며, 도구별 권한, 서버 측 자격 증명 보관, 단일 감사 로그를 제공합니다.
• 장시간 호출 진행 상황: 도구가 실행되는 동안 진행 상황을 스트리밍합니다.

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