Servidor MCP

Inicio rápido

1. Crea una clave API en la consola, en la página Claves API. Para un agente, asígnale un límite de gasto y una lista de modelos permitidos.
2. Añade el servidor a tu cliente con uno de los fragmentos de abajo, leyendo la clave desde una variable de entorno en lugar de pegarla en un archivo.
3. Pídele a tu agente, por ejemplo: “Lista los tres modelos más baratos que admiten herramientas, luego pide al más rápido que resuma este archivo y dime cuánto ha costado.”

Conecta tu cliente

Todos los clientes usan el mismo endpoint y la misma cabecera. Primero define SYNTHORAI_API_KEY en tu entorno.

Claude Code

Ejecuta /mcp dentro de Claude Code para comprobar la conexión. Añade --scope user para que el servidor esté disponible en todos los proyectos, o haz commit del formato .mcp.json para compartirlo con tu equipo (la clave se queda en el entorno de cada desarrollador).

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

Ponlo en ~/.cursor/mcp.json (todos los proyectos) o en .cursor/mcp.json (un solo proyecto).

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

VS Code (GitHub Copilot)

Ponlo en .vscode/mcp.json. VS Code pide la clave una sola vez y la guarda de forma segura.

{
  "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

Ponlo en ~/.codex/config.toml, o ejecuta 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

Los servidores de OpenAI llaman al endpoint en tu nombre, así que deja vacía la lista blanca de IP de la clave (o permite los rangos de salida de OpenAI). Usa allowed_tools para exponer solo las herramientas que necesita el modelo.

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

Funciona igual con cualquier framework basado en los SDK de cliente MCP (LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra …): apunta su transporte Streamable HTTP al endpoint con la cabecera.

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

Los conectores personalizados de Claude Desktop y claude.ai inician sesión con OAuth, que este servidor aún no ofrece (consulta la hoja de ruta más abajo). Mientras tanto, Claude Desktop puede conectarse a través del puente mcp-remote, que añade la cabecera por ti:

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

curl

El servidor es JSON-RPC simple sobre HTTP, así que no necesitas ningún SDK. No hace falta handshake: cada solicitud es independiente.

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"}}}'

Respuesta de ejemplo

{
  "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-…"
    }
  }
}

Herramientas

tools/list devuelve solo las herramientas que tu clave puede usar: se filtran por tipo de clave y por las funciones habilitadas para tu workspace (la generación de imágenes y de vídeo está en vista previa limitada). Las herramientas que ejecutan un modelo cuestan exactamente lo mismo que la llamada REST; todas las demás son gratuitas.

Clave de inferencia

Clave de provisioning

Clave de facturación

list_models, get_model y get_pricing están disponibles para todos los tipos de clave; con una clave de inferencia, list_models muestra solo los modelos que esa clave puede llamar.

Cómo son los resultados

Cada resultado incluye un bloque de texto legible y los mismos datos en JSON en structuredContent, para que puedan usarlo tanto los clientes de chat como los programas. Las imágenes y el audio se devuelven como contenido de imagen y de audio, y los vídeos como enlaces. Las herramientas que ejecutan un modelo terminan con una línea de recibo (modelo, tokens, coste y request_id) que get_generation puede consultar más tarde.

Permisos y seguridad

• Las mismas reglas que la API REST. Cada llamada a una herramienta la ejecuta el endpoint REST que indica, con tu clave: autenticación, tipo de clave, lista blanca de IP, lista de modelos permitidos, límite de gasto, límites de tasa y facturación se aplican sin cambios. MCP no añade ningún permiso ni se salta ninguna comprobación.
• Mínimo privilegio por tipo de clave. Las claves de inferencia no pueden gestionar claves ni leer la facturación del workspace; las claves de provisioning no pueden llamar a modelos; las claves de facturación son de solo lectura.
• Indicaciones de aprobación. Cada herramienta lleva anotaciones MCP. Las herramientas de solo lectura se marcan con readOnlyHint; las que gastan dinero no son de solo lectura; update_api_key, delete_api_key y cancel_video se marcan con destructiveHint. Los clientes las usan para decidir qué preguntarte antes de ejecutarlas.
• Clave recomendada para agentes: una clave de inferencia dedicada con un límite de gasto que se reinicia a diario, una lista allowed_models y una lista blanca de IP cuando el agente se ejecuta en hosts conocidos. Revócala por separado sin tocar las claves de producción.
• Secretos y contenido no fiable. create_api_key devuelve la nueva clave una sola vez: indícale a tu agente dónde guardarla. Trata la salida del modelo y los resultados de las herramientas como entrada no fiable (prompt injection) antes de dejar que un agente actúe a partir de ellos.

Detalles del protocolo

Solución de problemas

Próximamente

• Inicio de sesión con OAuth, para que los conectores de claude.ai, Claude Desktop y ChatGPT puedan conectarse sin pegar una clave, con credenciales de corta duración y gasto limitado.
• Gateway MCP: el mismo endpoint agregando también servidores MCP de terceros (GitHub, Slack, los tuyos propios) bajo tu clave, con permisos por herramienta, credenciales guardadas en el servidor y un único registro de auditoría.
• Progreso en llamadas largas, transmitido mientras se ejecuta una herramienta.

Relacionado: Claves API · Claves de provisioning · API de facturación · Chat Completions