Servidor MCP

Início rápido

1. Crie uma chave de API no console, na página Chaves de API. Para um agente, defina um limite de gasto e uma lista de permissões de modelos.
2. Adicione o servidor ao seu cliente com um dos trechos abaixo, lendo a chave de uma variável de ambiente em vez de colá-la em um arquivo.
3. Peça ao seu agente, por exemplo: “Liste os três modelos mais baratos que suportam ferramentas, depois peça ao mais rápido para resumir este arquivo e me diga quanto custou.”

Conecte seu cliente

Todos os clientes usam o mesmo endpoint e o mesmo cabeçalho. Primeiro, defina SYNTHORAI_API_KEY no seu ambiente.

Os clientes que se conectam por login (claude.ai, Claude Desktop, ChatGPT) não precisam de chave. Adicione o endpoint acima como conector e entre na Synthorai: você escolhe o workspace e o que a conexão pode fazer. Ela recebe uma chave própria, com validade, listada em Chaves de API, onde pode ser removida.

Claude Code

Execute /mcp no Claude Code para verificar a conexão. Adicione --scope user para disponibilizar o servidor em todos os projetos, ou faça commit do formato .mcp.json para compartilhá-lo com sua equipe (a chave continua no ambiente de cada desenvolvedor).

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

Coloque isto em ~/.cursor/mcp.json (todos os projetos) ou em .cursor/mcp.json (um projeto).

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

VS Code (GitHub Copilot)

Coloque isto em .vscode/mcp.json. O VS Code pede a chave uma vez e a armazena com segurança.

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

Coloque isto em ~/.codex/config.toml ou execute 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

Os servidores da OpenAI chamam o endpoint em seu nome, então deixe vazia a lista de permissões de IP da chave (ou libere as faixas de saída da OpenAI). Use allowed_tools para expor apenas as ferramentas de que o modelo precisa.

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 da mesma forma com qualquer framework construído sobre os SDKs de cliente MCP (LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra …): aponte o transporte Streamable HTTP dele para o endpoint, com o cabeçalho.

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

O Claude Desktop se conecta por login: adicione o endpoint como conector personalizado, sem precisar de chave. Para usar uma chave sua, conecte-se pela ponte mcp-remote, que adiciona o cabeçalho para você:

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

curl

O servidor é JSON-RPC puro sobre HTTP, então nenhum SDK é necessário. Não há handshake: cada requisição é independente.

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

Exemplo de resposta

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

Ferramentas

tools/list retorna apenas as ferramentas que sua chave pode usar: a lista é filtrada pelo tipo de chave e pelos recursos habilitados no seu workspace (a geração de imagens e de vídeos está em prévia limitada). Ferramentas que executam um modelo custam exatamente o mesmo que a chamada REST; todas as outras são gratuitas.

Chave de inferência

Chave de provisioning

Chave de cobrança

Chave de administração: log de requisições e uso

Chave de administração: biblioteca de prompts

Chave de administração: workspace

list_models, get_model e get_pricing estão disponíveis para todos os tipos de chave; com uma chave de inferência, list_models mostra apenas os modelos que essa chave pode chamar.

Controle o que uma conexão pode fazer

• Para o workspace. Em Configurações > MCP, um administrador ativa ou desativa o MCP, escolhe os grupos de ferramentas que as conexões podem usar e decide se ferramentas que alteram algo podem ser usadas. Em uma instância dedicada, o MCP fica desativado até que um administrador o ative.
• Para uma conexão. Envie X-MCP-Readonly: true para remover todas as ferramentas que alteram algo ou gastam dinheiro, e X-MCP-Toolsets: logs,prompts para manter apenas esses grupos (usage, logs, prompts, keys, workspace, inference). Clientes que não conseguem definir cabeçalhos colocam ?readonly=true&toolsets=logs,prompts na URL.
• Tudo isso só retira ferramentas. Uma ferramenta aparece na lista quando os escopos da chave, as configurações do workspace e os limites da própria conexão a permitem.
• Toda alteração é registrada. Uma alteração feita via MCP fica no log de auditoria com a chave e o nome do cliente.

Como são os resultados

Todo resultado traz um bloco de texto legível e os mesmos dados em JSON em structuredContent, para que tanto clientes de chat quanto programas possam usá-lo. Imagens e áudio voltam como conteúdo de imagem e de áudio; vídeos, como links. Ferramentas que executam um modelo terminam com uma linha de recibo (modelo, tokens, custo e request_id) que pode ser consultada depois com get_generation.

Permissões e segurança

• As mesmas regras da API REST. Cada chamada de ferramenta é executada pelo endpoint REST indicado, com a sua chave: autenticação, tipo de chave, lista de permissões de IP, lista de permissões de modelos, limite de gasto, limites de taxa e cobrança se aplicam sem alteração. O MCP não concede nenhuma permissão extra nem pula nenhuma verificação.
• Privilégio mínimo por chave. Uma chave de inferência não pode gerenciar chaves nem ler os dados de cobrança do workspace; uma chave de administração não pode chamar modelos e só faz o que seus escopos indicam.
• Dicas de aprovação. Toda ferramenta traz anotações MCP. Ferramentas somente leitura são marcadas com readOnlyHint; ferramentas que gastam dinheiro não são somente leitura; update_api_key, delete_api_key e cancel_video são marcadas com destructiveHint. Os clientes usam essas marcações para decidir o que perguntar a você antes de executar.
• Chave recomendada para agentes: uma chave de inferência dedicada, com limite de gasto redefinido diariamente, uma lista allowed_models e uma lista de permissões de IP quando o agente roda em hosts conhecidos. Revogue-a isoladamente, sem mexer nas chaves de produção.
• Segredos e conteúdo não confiável. create_api_key retorna a nova chave uma única vez: diga ao seu agente onde armazená-la. Trate a saída do modelo e os resultados das ferramentas como entrada não confiável (prompt injection) antes de deixar um agente agir com base neles.

Detalhes do protocolo

Solução de problemas

Em breve

• Gateway MCP: o mesmo endpoint também agregando servidores MCP de terceiros (GitHub, Slack, os seus próprios) sob a sua chave, com permissões por ferramenta, credenciais mantidas no servidor e um único log de auditoria.
• Progresso de chamadas longas, transmitido enquanto uma ferramenta é executada.

Relacionados: Chaves de API · Chaves de provisioning · API de cobrança · Chat Completions