Crie já
BR
Codex · MCP Server

Codex MCP Server: mensageria e e-mail no seu produto

Três linhas de config.toml conectam o Servidor MCP da Unipile. O Codex então cria recursos de LinkedIn, WhatsApp e e-mail no seu produto.
Conectar a Unipile ao Codex Obter uma chave de API
Teste grátis de 7 dias, sem cartão de crédito.
Codex · crm-app
Unipile MCP conectado
Sarah
Adicione a busca de pessoas do LinkedIn ao meu CRM.
Ler endpointPOST /v2/{account_id}/linkedin/searchschema carregado
Adicionei a rota de busca e a lista de resultados. Cada linha guarda o ID do provedor para o perfil.
3 arquivos alterados · testado na aplicação Development
Descreva o próximo recurso…
O objetivo

O que você quer construir

Adicionar uma conexão de LinkedIn, WhatsApp, e-mail ou calendário ao seu produto. Isso significa ler uma referência de API, escolher os endpoints certos, montar o Hosted Auth e seus callbacks e depois guardar os IDs certos da busca até a mensagem. Com o servidor MCP da Unipile no Codex, o agente faz essa leitura por você e escreve o código na sua stack, pelo CLI, pela extensão da IDE ou pelo app de desktop.
Conecte o servidor MCP da Unipile ao CodexUnipile MCP conectado
Selecione os canais que quer conectardeveloper.unipile.com/mcp
Conectar todos os canais9 canais
LinkedInLinkedIn/v2/{account_id}/chats
WhatsAppWhatsApp/v2/{account_id}/chats
InstagramInstagram/v2/{account_id}/chats
TelegramTelegram/v2/{account_id}/chats
GmailGmail/v2/{account_id}/emails
OutlookOutlook/v2/{account_id}/emails
IMAPIMAP/v2/{account_id}/emails
Google CalendarGoogle Calendar/v2/{account_id}/calendars
Outlook CalendarOutlook Calendar/v2/{account_id}/calendars
↑↓navegar espaçoselecionar ↵conectaruma URL, um header
Sem isso Abas, adivinhação, código de cola
O Codex adivinha nomes de endpoints e payloads a partir dos dados de treino, e erra os IDs.
Você cola schemas da referência no chat, um endpoint de cada vez.
A primeira chamada real acontece em produção, depois do code review.
Com o servidor MCP da Unipile O resultado na sua aplicação
Uma rota de conexão e um botão nas configurações: cada usuário vincula a própria conta pelo Hosted Auth.
Um receptor de webhook e uma caixa de entrada que mostra mensagens e e-mails conforme eles chegam.
Cada requisição já executada uma vez na sua aplicação Development antes de você revisar o diff.
config.toml, CLI e IDE

Adicione o servidor MCP da Unipile ao Codex

O servidor é remoto: uma URL sobre streamable HTTP e um header. Sem npx, sem processo local. Uma entrada no config.toml é lida pelo Codex CLI, pela extensão Codex da IDE e pelo app de desktop do ChatGPT, então você configura uma vez só.
Codex CLI instalado (npm i -g @openai/codex) ou a extensão Codex da IDE, com login feito.
Uma aplicação Development no dashboard da Unipile, com um Scope e uma chave de API de conta com escopo.
Pelo menos uma conta de teste conectada a esse Scope via Hosted Auth, para que o agente possa executar requisições reais.
1
codex mcp add e depois o headerregistra a URL em ~/.codex/config.toml
G
Configuração global~/.codex/config.toml
P
Configuração por projeto.codex/config.toml (projeto confiável)
E
Chave vinda de uma variável de ambienteenv_http_headers
?
Por que duas etapas no CLI?O codex mcp add aceita --url e uma variável de bearer token, mas nenhuma flag de header personalizado. O servidor da Unipile autentica com X-API-KEY, então o comando registra a URL e o header vai para o config.toml, na mão ou com env_http_headers.
terminal
# 1. Registre o servidor MCP hospedado da Unipile (config global) codex mcp add unipile --url "https://developer.unipile.com/mcp?branch=v2.0" # Added global MCP server 'unipile'. # 2. Adicione o header X-API-KEY à entrada em ~/.codex/config.toml [mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" http_headers = { "X-API-KEY" = "your-scoped-api-key" } # 3. Verifique codex mcp get unipile
[mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" http_headers = { "X-API-KEY" = "your-scoped-api-key" }
[mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" http_headers = { "X-API-KEY" = "your-scoped-api-key" } # Lido apenas dentro de um projeto confiável. Mantenha a chave fora do git: prefira env_http_headers.
[mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" } # export UNIPILE_API_KEY=your-scoped-api-key antes de iniciar o codex
Salve o arquivo e reinicie o Codex. O codex mcp list mostra unipile como enabled, e o /mcp dentro de uma sessão lista o servidor. Verificado no codex-cli 0.154.0.
O que cada linha faz, verificado no codex-cli 0.154.0
codex mcp add unipileCria a tabela [mcp_servers.unipile] no config.toml global. O nome é seu; deixe curto, ele vira o prefixo das ferramentas.
--url "https://developer.unipile.com/mcp?branch=v2.0"Transporte streamable HTTP. Coloque a URL entre aspas: a interrogação é um caractere de glob no zsh.
http_headers = { "X-API-KEY" = "…" }Header estático enviado em toda requisição. Use sua chave de API de conta com escopo, nunca uma chave Service ou de conta global.
env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" }Mesmo header, com o valor lido do ambiente na inicialização. É a forma certa para um config.toml de projeto versionado.
startup_timeout_sec = 30Opcional. O padrão é 10 s; aumente se o primeiro handshake expirar em uma rede lenta.
enabled = falseOpcional. Desativa o servidor sem apagar a entrada, útil para alternar entre chaves de Development e de Production.
A parte específica do Codex

Mantenha sua chave de API fora do config.toml

O http_headers grava a chave em texto puro em um arquivo que acaba em backups e, no caso de uma config de projeto, no git. O Codex tem três formas de enviar o header X-API-KEY; escolha a que combina com o lugar onde o arquivo está.
1http_headers, valor estáticoA forma da documentação da Unipile. Serve para uma config de usuário na sua própria máquina, nunca para um arquivo compartilhado em um repositório.http_headers = { "X-API-KEY" = "your-scoped-api-key" }
2env_http_headers, lido na inicializaçãoMapeia o nome do header para o nome de uma variável de ambiente. O arquivo não carrega nenhum segredo, e cada dev exporta a própria chave com escopo. É a forma certa para um config.toml de projeto.env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" } export UNIPILE_API_KEY=your-scoped-api-key
3http_headers_helper, a partir de um comandoUm comando local que imprime os headers como JSON, para times que buscam as chaves em um cofre. E não esqueça do CODEX_HOME: ele muda todo o diretório de configuração, então um servidor salvo em um terminal pode sumir em outro.http_headers_helper = "./scripts/unipile-headers.sh"
Verificar

Verifique a conexão

Três checagens: no CLI, dentro de uma sessão e depois com um prompt que só lê a especificação. Nenhuma delas toca em uma conta conectada.
1No Codex CLIO list imprime uma linha por servidor, com URL e status. O get mostra o transporte, os headers e o comando de remoção.codex mcp list codex mcp get unipile
2Dentro de uma sessãoNo TUI do Codex, na extensão da IDE (menu de engrenagem, MCP servers) e no app de desktop do ChatGPT (Settings, MCP servers), aparece a mesma entrada: uma config, três superfícies./mcp # Status enabled e Auth Unsupported são esperados: o servidor usa um header, não OAuth
3Em um chat, sem tocar em nenhuma contaPergunte algo que só exija a leitura da especificação da API. Se o agente responder com rotas e parâmetros reais, o servidor está conectado.Usando o Unipile MCP, liste os endpoints de busca de pessoas no LinkedIn e os parâmetros obrigatórios de cada um.
Prompts, não código de cola

Entregue o prompt ao seu agente

Três tarefas de integração, cada uma com o prompt exato para colar no Codex, os endpoints Unipile que o agente lê e executa e o que chega ao seu projeto. Os paths estão completos, sobre a URL base da API https://api.unipile.com, com sua chave com escopo no X-API-KEY como header.
Codex · crm-appAplicação Development
Adicione busca de pessoas do LinkedIn ao meu CRM e depois deixe o usuário abrir o perfil selecionado e iniciar uma conversa a partir dele.
Buscar endpoints"linkedin search people profile"3 resultados
Executar requisiçãoPOST /v2/{account_id}/linkedin/search10 resultados
Adicionei GET /api/linkedin/search (palavras-chave, cursor de paginação) e GET /api/linkedin/profiles/:identifier. A lista de resultados guarda o ID de provedor devolvido pela busca, a rota de perfil o reaproveita, e o botão "Mensagem" o repassa para a criação do chat. Rodei os dois na aplicação Development.4 arquivos alterados · testado na aplicação Development

Um identificador do resultado da busca até a conversa

A parte difícil de um recurso de LinkedIn não são as chamadas, é manter o mesmo identificador da linha da busca até o perfil e depois até a mensagem. O Codex lê os três contratos pelo servidor, vê qual campo carrega esse identificador em cada resposta e escreve as rotas sem que nada seja adivinhado.
Endpoints usados pelo agente
POST/v2/{account_id}/linkedin/searchGET/v2/{account_id}/users/{identifier}POST/v2/{account_id}/chats
Erro comum: Buscar com uma conta e enviar mensagem com outra. O perfil e o chat precisam ser abertos na account_id que executou a busca.
Criar uma integração LinkedIn
Codex · messaging-sdkAplicação Development
Gere um cliente tipado em Node.js e em Python para as rotas de chats e de e-mails da Unipile que usamos, a partir dos schemas da API, com retentativas em 429.
Ler endpointGET /v2/{account_id}/emailsschema carregado
Executar requisiçãoGET /v2/{account_id}/chats200 OK
Escrevi unipile-client.ts e unipile_client.py a partir dos schemas de requisição e de resposta: métodos tipados de listagem e de envio para chats e e-mails, helper de paginação por cursor e backoff exponencial em 429 com o header Retry-After. Os dois clientes executaram as chamadas de listagem na aplicação Development.2 clientes gerados · schemas lidos pelo servidor

Clientes tipados a partir dos schemas reais, não de memória

O Codex não adivinha os payloads. Ele lê o body da requisição e o schema de resposta de cada rota pelo servidor, gera os tipos e executa uma chamada por método na sua aplicação Development antes de você revisar o diff. Os SDKs oficiais de Node.js e Python continuam sendo a referência; o cliente gerado é seu, para manter enxuto.
Endpoints usados pelo agente
GET/v2/{account_id}/chatsPOST/v2/{account_id}/chats/{chat_id}/messages/sendGET/v2/{account_id}/emailsPOST/v2/{account_id}/emails/send
Erro comum: Repetir um envio depois de um timeout sem checagem de idempotência. Uma mensagem só pode sair uma vez; repita as chamadas de leitura, não as de escrita.
Ver os SDKs oficiais
Codex · saas-backendAplicação Development
Dê suporte a várias contas conectadas por usuário do meu SaaS: eles podem vincular várias contas de LinkedIn e de e-mail e escolher por qual enviar.
Ler endpointGET /v2/accountsschema carregado
Executar requisiçãoGET /v2/accounts3 contas
Adicionei uma tabela accounts indexada por usuário e account_id, um seletor no compositor, e POST /api/messages que envia pela conta selecionada. Os estados de reconexão vindos da rota de contas aparecem como badge. Verificado com três contas na aplicação Development.5 arquivos alterados · 3 contas, um compositor

Um usuário, várias contas, um Scope por workspace

Cada conta que seus usuários conectam pelo Hosted Auth ganha o próprio account_id. O agente desenha o mapeamento entre seus usuários e esses IDs, lê a rota de status da conta para exibir os estados de reconexão e de checkpoint, e roteia cada envio para a conta que o usuário escolheu.
Endpoints usados pelo agente
GET/v2/accountsGET/v2/accounts/{account_id}POST/v2/auth/linkPOST/v2/{account_id}/chats
Erro comum: Guardar o ID de conta no workspace em vez de no usuário. As contas pertencem a quem as conectou; o workspace apenas agrupa Scopes e chaves.
Implementar o Hosted Auth com um agente
Do Development para a Production

Teste primeiro em uma aplicação Development

O dashboard da Unipile separa uma aplicação Development de uma de Production. Dê ao Codex uma chave com escopo da aplicação Development, com uma ou duas contas de teste conectadas via Hosted Auth. O agente executa requisições reais nessas contas, em nome do usuário autenticado que as vinculou, dentro dos limites de cada provedor, e nada toca as contas dos seus usuários até você publicar. Mantenha default_tools_approval_mode em prompt enquanto desenvolve, se quiser confirmar cada escrita.
Valide o fluxo de conexão de ponta a ponta: link de autenticação criado no servidor, ID de conta guardado no usuário.
Valide uma leitura e uma escrita por recurso: listar chats, enviar uma mensagem na conta de teste.
Valide uma entrega de webhook e um estado de reconexão ou checkpoint antes de trocar a chave para a Production.
crm-app · DevelopmentUsada pelo Codex
Escopodev-tests · 2 contas
Chavescoped Account API key
ContasConta de teste LinkedIn, caixa de e-mail Gmail de teste
Webhooks1 endpoint · eventos de mensagem
crm-app · ProductionSem alterações
Escopouma por workspace
Chavescoped keys, in your backend only
Contasas próprias contas dos seus usuários, via Hosted Auth
Solução de problemas

Erros comuns e o que eles significam

O que você vê quando uma entrada MCP do Codex está errada e a correção de cada caso. Quase todos se resumem ao arquivo, ao TOML, ao nível de confiança ou à chave.
O servidor não aparece depois de editar o config.toml
O codex mcp list não imprime nada, ou a entrada some dentro de uma sessão. CorreçãoReinicie o cliente: o arquivo é lido na inicialização. Depois confira CODEX_HOME: ele muda todo o diretório de configuração, então um servidor salvo em um terminal pode ficar invisível em outro. Execute codex mcp list no mesmo shell de onde você inicia o Codex.
A configuração de projeto é ignorada
.codex/config.toml está na raiz do repositório, e o Codex continua usando a entrada global, ou nenhuma. CorreçãoO Codex carrega a camada de projeto apenas para um projeto confiável. Marque-o com trust_level = "trusted" sob [projects."/path/to/repo"] na config de usuário, ou mova a entrada para ~/.codex/config.toml.
TOML inválido
O arquivo não é parseado e todos os servidores somem de uma vez. CorreçãoUma tabela chamada [mcp_servers.unipile] exatamente assim, aspas em torno de "X-API-KEY" na tabela de headers, e uma tabela, não uma string, para http_headers. Uma chave de fechamento faltando derruba o arquivo inteiro.
401 Unauthorized nas requisições
O servidor aparece na lista e lê a especificação, mas executar uma requisição falha. CorreçãoO header está faltando, a variável indicada em env_http_headers não foi exportada no shell que iniciou o Codex, ou a chave é uma chave Service ou de conta global em vez de uma chave de API de conta com escopo da sua aplicação Development.
As configurações dizem que o servidor está indisponível
A extensão da IDE ou o app de desktop sinaliza o servidor, mas as ações funcionam. CorreçãoEssa checagem procura resources, e o servidor da Unipile expõe actions, não resources. Confirme com /mcp dentro de uma sessão e executando uma chamada de leitura. Nada a mudar do seu lado.
Timed out
A inicialização ou uma chamada ultrapassa o limite. CorreçãoOs padrões são startup_timeout_sec = 10 e tool_timeout_sec = 60. O servidor é remoto, não há processo para iniciar: confira a URL (?branch=v2.0 incluído), a rede e qualquer proxy corporativo antes de aumentar os timeouts.
6000+ Empresas que inovam com a Unipile
Com a confiança dos líderes do setor
1 API
Simplificar as operações de todos os principais canais de comunicação
2 dias
Obtenha integração ao vivo rapidamente com o mínimo de configuração
30%
Redução dos esforços e recursos de manutenção

Segurança e conformidade incorporadas

Proteção de nível empresarial para seus dados e fluxos de trabalho Saiba mais sobre nossa segurança
SOC 2 Tipo II
SOC 2 Tipo II
Certificado
Controles de segurança auditados de forma independente, garantindo a proteção dos dados e a integridade operacional.
GDPR
GDPR
Em conformidade
Conformidade total com os regulamentos europeus de proteção de dados para a privacidade do usuário.
99.9%
Tempo de atividade da plataforma nos últimos 24 meses
24/7
Suporte global com API de alto desempenho

FAQ do servidor MCP no Codex

As perguntas que as pessoas realmente digitam: config.toml em vez de mcp.json, onde ele fica, codex mcp add, como manter a chave fora do arquivo, as três superfícies, o que checar quando nada aparece, timeouts e chaves.
Não. O Codex guarda a configuração MCP em ~/.codex/config.toml, em TOML, uma tabela por servidor chamada [mcp_servers.<name>]. Não existe mcp.json no Codex, e o arquivo não é criado na instalação: você o cria, ou o codex mcp add o cria para você. Um projeto confiável também pode carregar um .codex/config.toml na própria raiz.
~/.codex/config.toml para a configuração de usuário, .codex/config.toml na raiz do repositório para a configuração de projeto. A variável de ambiente CODEX_HOME muda todo o diretório de configuração: quando um servidor aparece em um terminal e não em outro, confira isso primeiro. O Codex CLI, a extensão da IDE e o app de desktop leem o mesmo arquivo.
Em parte. O codex mcp add unipile --url "https://developer.unipile.com/mcp?branch=v2.0" escreve a tabela de um servidor streamable HTTP, e o --bearer-token-env-var cobre servidores que aceitam um token Bearer. O servidor da Unipile autentica com um header X-API-KEY que o comando não consegue definir, então você acrescenta http_headers ou env_http_headers à entrada criada por ele. Verificado no codex-cli 0.154.0.
Use env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" }: ele mapeia o nome do header para o nome de uma variável de ambiente em vez de um valor, então o arquivo pode ser versionado sem segredo e cada dev exporta a própria chave de API de conta com escopo. O http_headers serve para valores estáticos, e o http_headers_helper deixa um comando local produzir os headers como JSON.
Sim. As três superfícies de um mesmo host Codex leem a mesma configuração, então um servidor adicionado uma vez fica disponível em todas. No app de desktop e na extensão você também pode adicioná-lo em Settings, MCP servers, Add server, escolhendo Streamable HTTP. Reinicie o cliente depois de salvar o arquivo.
Quatro causas, nesta ordem: o cliente não foi reiniciado; o arquivo está sob um CODEX_HOME diferente do shell atual; a tabela está em um .codex/config.toml de projeto e o projeto não está marcado como trust_level = "trusted", caso em que o Codex ignora a camada de projeto inteira; ou o TOML é inválido. Execute codex mcp list, e depois /mcp dentro de uma sessão.
startup_timeout_sec sobrescreve o timeout padrão de 10 segundos na inicialização e tool_timeout_sec o timeout padrão de 60 segundos por ferramenta, ambos sob a tabela do servidor. O servidor da Unipile é remoto, em HTTP, sem processo local para iniciar, então um timeout de inicialização quase sempre aponta para a URL, a rede ou um proxy corporativo, não para o servidor.
O servidor responde sem chave quando o agente só lê a especificação da API. Para executar requisições reais, crie um Scope na sua aplicação Development, associe as contas de teste e gere uma chave de API de conta com escopo para esse Scope. Nunca dê a um cliente MCP uma chave Service ou uma chave de conta global.