Servidor MCP

O Ephemeral oferece um servidor Model Context Protocol (MCP), para que agentes de IA como Claude, ChatGPT e os agentes do seu editor possam iniciar execuções, aguardar resultados e ler seus fluxos de trabalho diretamente. Valem as mesmas chaves de API, papéis, orçamentos e validações da API REST. Eles também podem salvar e excluir fluxos de trabalho, gerenciar agendamentos e listar seus arquivos, de modo que um agente configura uma tarefa recorrente de ponta a ponta.

Entrar com OAuth

Os clientes que oferecem suporte à autorização do MCP precisam apenas da URL https://app.ephemer.al/mcp. O cliente descobre o login do Ephemeral pela resposta 401 do servidor e pelos metadados do recurso protegido dele, se registra e abre uma página em que você entra, escolhe uma organização e aprova. Depois ele guarda um token de acesso válido por uma hora e um token de atualização, e você não é perguntado de novo até revogar o acesso.

• O acesso vale para a organização que você escolher, com o papel que você aprovar: member ou admin. Só proprietários e administradores da organização podem conceder admin, e o de membro basta para tudo, exceto criar, alterar ou excluir agendamentos, que exige admin.
• Os tokens funcionam somente na API do Ephemeral (https://app.ephemer.al), nunca em outros serviços.
• Veja ou revogue cada aplicativo conectado em “Aplicativos autorizados”, na página da sua conta.
• Os metadados do servidor de autorização ficam em https://ephemer.al/.well-known/oauth-authorization-server. Os clientes precisam usar PKCE (S256).

Conectar com uma chave de API

Crie uma chave de API em Chaves, no painel. Uma chave de membro cobre execuções, fluxos de trabalho e arquivos; use uma chave de administrador se o agente também deve criar, alterar ou excluir agendamentos. O servidor fica em https://app.ephemer.al/mcp e usa o transporte Streamable HTTP; cada requisição leva a chave como token de portador.

Claude Code

Adicione o servidor uma vez; depois ele fica disponível em todas as sessões.

claude mcp add --transport http ephemeral https://app.ephemer.al/mcp \
  --header "Authorization: Bearer $EPHEMERAL_API_KEY"

Cursor, VS Code e outros clientes com suporte a HTTP

A maioria dos clientes aceita um servidor remoto com cabeçalhos nas configurações de MCP:

{
  "mcpServers": {
    "ephemeral": {
      "url": "https://app.ephemer.al/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop

O Claude Desktop inicia servidores locais a partir do arquivo de configuração (claude_desktop_config.json). A ponte mcp-remote o conecta a um servidor remoto e repassa o cabeçalho:

{
  "mcpServers": {
    "ephemeral": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.ephemer.al/mcp", "--header", "Authorization:${EPHEMERAL_AUTH}"],
      "env": { "EPHEMERAL_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

Ferramentas

Cada ferramenta tem um esquema de entrada, que os clientes mostram ao modelo, e devolve texto e conteúdo estruturado. Falhas que a API REST informa como erros voltam como erros de ferramenta com a mesma mensagem.

Experimente

O endpoint recebe mensagens JSON-RPC 2.0 por POST. Normalmente o cliente faz isso; com curl, uma chamada fica assim:

curl -sS https://app.ephemer.al/mcp \
  -H "Authorization: Bearer $EPHEMERAL_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":"create_run","arguments":{"prompt":"Summarize https://example.com","web":true,"max_cost_micros":200000}}}'

Salvar um fluxo de trabalho e agendá-lo

Um agente transforma uma tarefa em um trabalho recorrente com duas chamadas. Primeiro save_workflow, com estes argumentos:

{
  "name": "weekly-report",
  "prompt": "Summarize last week's support tickets from the helpdesk connection and list the three biggest themes.",
  "connections": { "helpdesk": { "ref": "helpdesk", "allowed_methods": ["GET"] } },
  "timeout_seconds": 600
}

Depois create_schedule (chave de administrador), aqui toda segunda-feira às 09:00 em Madri; antes, preview_schedule mostra os próximos inícios:

{
  "workflow": "weekly-report",
  "cron": "0 9 * * 1",
  "timezone": "Europe/Madrid",
  "max_cost_micros": 500000
}

Papéis

A maioria das ferramentas são operações que uma chave de membro já pode executar na API REST, e as de agendamento seguem a mesma regra da API REST: ler, pré-visualizar e executar um agendamento agora só exige uma chave de membro, enquanto create_schedule, update_schedule e delete_schedule exigem uma chave de administrador ou proprietário e, caso contrário, respondem com um erro de ferramenta (status 403). Não há ferramenta para criar chaves, alterar conexões ou gerenciar o faturamento. A chave também define a organização: as execuções são cobradas dela e aparecem no seu histórico.

Segurança

• Nada é executado sem chave. Qualquer pessoa pode inicializar e listar as ferramentas, que já são públicas; cada chamada de ferramenta exige uma chave válida e recebe 401 sem ela.
• Os tokens de acesso OAuth expiram em uma hora, ficam limitados a uma organização e ao papel aprovado, e podem ser revogados a qualquer momento na página da sua conta.
• Os orçamentos valem. Toda execução tem um teto de custo, de max_cost_micros ou do padrão da organização, e as mesmas verificações de saldo da API.
• Conexões são referências salvas. Um agente só pode citar uma conexão que sua organização salvou e pode restringi-la com allowed_methods (por exemplo, só GET) ou allowed_tools. Ele nunca pode fornecer uma URL ou uma credencial.
• A retenção zero de dados está disponível por execução. A saída dessa execução é liberada na primeira leitura.
• Apenas POST é aceito. Não há sessões nem mensagens iniciadas pelo servidor.

Protocolo

As versões de protocolo 2025-11-25, 2025-06-18 e 2025-03-26 são aceitas; o servidor responde com a versão que o cliente pede. GET e DELETE devolvem 405. Um documento de descoberta é publicado em /.well-known/mcp/server-card.json.