Crea ora
IT
Codex · Server MCP

Server MCP per Codex: messaggistica ed email nel suo prodotto

Tre righe di config.toml collegano il Server MCP Unipile. Codex costruisce poi funzionalità LinkedIn, WhatsApp ed email nel suo prodotto.
Connettere Unipile a Codex Ottenga una chiave API
Prova gratuita di 7 giorni, senza carta di credito.
Codex · crm-app
Unipile MCP connesso
Sarah
Aggiungi la ricerca di persone LinkedIn al mio CRM.
Lettura endpointPOST /v2/{account_id}/linkedin/searchschema caricato
Aggiunti la route di ricerca e la lista dei risultati. Ogni riga conserva il provider ID del profilo.
3 file modificati · testato sull'app Development
Descriva la prossima funzionalità…
L'obiettivo

Che cosa si vuole ottenere

Aggiungere al suo prodotto una connessione LinkedIn, WhatsApp, email o calendario. Significa leggere un riferimento API, scegliere gli endpoint giusti, collegare Hosted Auth e i suoi callback, e poi conservare gli ID corretti dalla ricerca fino al messaggio. Con il server MCP di Unipile in Codex, è l'agente a fare quella lettura per lei e a scrivere il codice nel suo stack, dalla CLI, dall'estensione per l'IDE o dall'app desktop.
Connettere il server MCP Unipile a CodexUnipile MCP connesso
Selezioni i canali da connetteredeveloper.unipile.com/mcp
Connetti tutti i canali9 canali
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
↑↓naviga spazioseleziona ↵connettiun URL, un header
Senza Schede aperte, tentativi, codice di collegamento
Codex indovina nomi di endpoint e payload dai dati di training, e sbaglia gli ID.
Si incollano gli schemi del riferimento nella chat, un endpoint alla volta.
La prima chiamata reale avviene in produzione, dopo la code review.
Con il server MCP di Unipile Il risultato nella sua applicazione
Una route di connessione e un pulsante Settings: ogni utente collega il proprio account tramite Hosted Auth.
Un ricevitore di webhook e una inbox che mostra messaggi ed email man mano che arrivano.
Ogni richiesta già eseguita una volta sulla sua applicazione Development prima di rivedere il diff.
config.toml, CLI e IDE

Aggiungere il server MCP Unipile a Codex

Il server è remoto: un URL su streamable HTTP e un header. Niente npx, nessun processo locale. Una sola voce in config.toml viene letta da Codex CLI, dall'estensione Codex per l'IDE e dall'app desktop ChatGPT, quindi la configura una volta sola.
Codex CLI installata (npm i -g @openai/codex) o estensione Codex per l'IDE, con accesso effettuato.
Un'applicazione Development nella dashboard Unipile, con uno Scope e una chiave API Account scoped.
Almeno un account di test collegato a quello Scope tramite Hosted Auth, così l'agente può eseguire richieste reali.
1
codex mcp add, poi l'headerregistra l'URL in ~/.codex/config.toml
G
Configurazione globale~/.codex/config.toml
P
Configurazione di progetto.codex/config.toml (progetto attendibile)
E
Chiave da una variabile d'ambienteenv_http_headers
?
Perché due passaggi nella CLI?codex mcp add accetta --url e una variabile con token bearer, ma nessun flag per header personalizzati. Il server Unipile si autentica con X-API-KEY, quindi il comando registra l'URL e l'header va in config.toml, a mano o con env_http_headers.
terminale
# 1. Registri il server MCP Unipile ospitato (configurazione globale) codex mcp add unipile --url "https://developer.unipile.com/mcp?branch=v2.0" # Added global MCP server 'unipile'. # 2. Aggiunga l'header X-API-KEY alla voce in ~/.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. Verifichi 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" } # Letta solo all'interno di un progetto attendibile. Tenga la chiave fuori da git: meglio 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 prima di avviare codex
Salvi il file e riavvii Codex. codex mcp list mostra unipile come abilitato, e /mcp all'interno di una sessione elenca il server. Verificato su codex-cli 0.154.0.
Cosa fa ogni riga, verificato su codex-cli 0.154.0
codex mcp add unipileCrea la tabella [mcp_servers.unipile] nel config.toml globale. Il nome lo sceglie lei; lo tenga breve, diventa il prefisso dei tool.
--url "https://developer.unipile.com/mcp?branch=v2.0"Trasporto streamable HTTP. Metta l'URL tra virgolette: il punto interrogativo è un carattere glob in zsh.
http_headers = { "X-API-KEY" = "…" }Header statico inviato a ogni richiesta. Usi la sua chiave API Account scoped, mai una chiave Service o Account globale.
env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" }Stesso header, valore letto dall'ambiente all'avvio. La forma giusta per un config.toml di progetto che vive in git.
startup_timeout_sec = 30Opzionale. Il valore predefinito è 10 s; lo aumenti se il primo handshake va in timeout su una rete lenta.
enabled = falseOpzionale. Disattiva il server senza eliminare la voce, utile per alternare chiavi Development e Production.
La parte specifica di Codex

Tenere la chiave API fuori da config.toml

http_headers scrive la chiave in chiaro in un file che finisce nei backup e, per una configurazione di progetto, in git. Codex offre tre modi per inviare l'header X-API-KEY; scelga quello adatto a dove si trova il file.
1http_headers, valore staticoLa forma usata nella documentazione Unipile. Va bene per una configurazione utente sulla sua macchina, mai per un file condiviso in un repository.http_headers = { "X-API-KEY" = "your-scoped-api-key" }
2env_http_headers, letto all'avvioAssocia il nome dell'header al nome di una variabile d'ambiente. Il file non contiene alcun segreto, ogni sviluppatore esporta la propria chiave scoped. La forma giusta per un config.toml di progetto.env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" } export UNIPILE_API_KEY=your-scoped-api-key
3http_headers_helper, da un comandoUn comando locale che stampa gli header in JSON, per i team che recuperano le chiavi da un vault. E si ricordi di CODEX_HOME: sposta l'intera cartella di configurazione, quindi un server salvato in un terminale può risultare assente in un altro.http_headers_helper = "./scripts/unipile-headers.sh"
Verifica

Verificare la connessione

Tre controlli: nella CLI, dentro una sessione, poi con un prompt che legge soltanto la specifica. Nessuno tocca un account collegato.
1Nella Codex CLIlist stampa una riga per server con URL e stato. get mostra il trasporto, gli header e il comando di rimozione.codex mcp list codex mcp get unipile
2Dentro una sessioneNella TUI di Codex, nell'estensione per l'IDE (menu a ingranaggio, MCP servers) e nell'app desktop ChatGPT (Settings, MCP servers) compare la stessa voce: una configurazione, tre superfici./mcp # Status enabled, Auth Unsupported è normale: il server usa un header, non OAuth
3In una chat, senza toccare un accountChieda qualcosa che legga soltanto la specifica dell'API. Se l'agente risponde con route e parametri reali, il server è collegato.Usando l'MCP di Unipile, elenca gli endpoint per la ricerca di persone su LinkedIn e i loro parametri obbligatori.
Prompt, non codice di collegamento

Dia il prompt al suo agente

Tre integrazioni, ciascuna con il prompt esatto da incollare in Codex, gli endpoint Unipile che l'agente legge ed esegue e ciò che arriva nel suo progetto. I percorsi sono completi, sull'URL di base dell'API https://api.unipile.com, con la sua chiave scoped passata nell'header X-API-KEY della richiesta.
Codex · crm-appApp Development
Aggiungi la ricerca di persone LinkedIn al mio CRM, poi permetti all'utente di aprire il profilo selezionato e di avviare una conversazione da lì.
Ricerca endpoint"linkedin search people profile"3 risultati
Esecuzione richiestaPOST /v2/{account_id}/linkedin/search10 risultati
Aggiunte GET /api/linkedin/search (parole chiave, cursore di paginazione) e GET /api/linkedin/profiles/:identifier. La lista dei risultati conserva il provider ID restituito dalla ricerca, la route del profilo lo riutilizza e il pulsante "Message" lo passa alla creazione della chat. Entrambe eseguite sull'app Development.4 file modificati · testato sull'app Development

Un solo identificatore dal risultato di ricerca alla conversazione

La parte difficile di una funzionalità LinkedIn non sono le chiamate, ma mantenere lo stesso identificatore dalla riga di ricerca al profilo e poi al messaggio. Codex legge i tre contratti tramite il server, vede quale campo contiene quell'identificatore in ogni risposta e scrive le route senza tirare a indovinare.
Endpoint usati dall'agente
POST/v2/{account_id}/linkedin/searchGET/v2/{account_id}/users/{identifier}POST/v2/{account_id}/chats
Errore comune: cercare con un account e scrivere con un altro. Il profilo e la chat vanno aperti sullo stesso account_id che ha eseguito la ricerca.
Costruire un'integrazione LinkedIn
Codex · messaging-sdkApp Development
Genera un client tipizzato Node.js e Python per le route chats ed emails di Unipile che usiamo, a partire dagli schemi dell'API, con retry sui 429.
Lettura endpointGET /v2/{account_id}/emailsschema caricato
Esecuzione richiestaGET /v2/{account_id}/chats200 OK
Scritti unipile-client.ts e unipile_client.py a partire dagli schemi di richiesta e risposta: metodi tipizzati di lista e invio per chat ed email, helper di paginazione a cursore, backoff esponenziale sui 429 con l'header Retry-After. Entrambi i client hanno eseguito le chiamate di lista sull'app Development.2 client generati · schemi letti tramite il server

Client tipizzati dagli schemi reali, non dalla memoria

Codex non tira a indovinare i payload. Legge il body della richiesta e lo schema della risposta di ogni route tramite il server, genera i tipi ed esegue una chiamata per metodo sulla sua applicazione Development prima che lei riveda il diff. Gli SDK ufficiali Node.js e Python restano il riferimento; il client generato è suo e può restare snello.
Endpoint usati dall'agente
GET/v2/{account_id}/chatsPOST/v2/{account_id}/chats/{chat_id}/messages/sendGET/v2/{account_id}/emailsPOST/v2/{account_id}/emails/send
Errore comune: ritentare un invio dopo un timeout senza un controllo di idempotenza. Un messaggio può partire una sola volta: ritenti le letture, non le scritture.
Vedere gli SDK ufficiali
Codex · saas-backendApp Development
Supporta più account collegati per ogni utente del mio SaaS: possono collegare diversi account LinkedIn ed email e scegliere quale usare per inviare.
Lettura endpointGET /v2/accountsschema caricato
Esecuzione richiestaGET /v2/accounts3 account
Aggiunta una tabella accounts con chiave per utente e account_id, un selettore nel composer e POST /api/messages che invia dall'account selezionato. Gli stati di riconnessione restituiti dalla route accounts compaiono come badge. Verificato con tre account sull'app Development.5 file modificati · 3 account, un solo composer

Un utente, diversi account, uno Scope per workspace

Ogni account che i suoi utenti collegano tramite Hosted Auth riceve il proprio account_id. L'agente progetta la mappatura tra i suoi utenti e quegli ID, legge la route di stato dell'account per mostrare gli stati di riconnessione e di checkpoint e instrada ogni invio verso l'account scelto dall'utente.
Endpoint usati dall'agente
GET/v2/accountsGET/v2/accounts/{account_id}POST/v2/auth/linkPOST/v2/{account_id}/chats
Errore comune: salvare l'account ID sul workspace invece che sull'utente. Gli account appartengono alla persona che li ha collegati; il workspace raggruppa solo Scope e chiavi.
Implementare Hosted Auth con un agente
Dallo sviluppo alla produzione

Testare prima su un'applicazione Development

La dashboard Unipile separa un' applicazione Development da una di Produzione. Dia a Codex una chiave scoped dell'applicazione Development, con uno o due account di test collegati tramite Hosted Auth. L'agente esegue richieste reali su quegli account, per conto dell'utente autenticato che li ha collegati e nei limiti di ogni provider, e nulla tocca gli account dei suoi utenti fino al rilascio. Tenga default_tools_approval_mode su prompt durante lo sviluppo, se vuole confermare ogni scrittura.
Validi il flusso di connessione end to end: auth link creato lato server, account ID salvato sull'utente.
Validi una lettura e una scrittura per funzionalità: elenco delle chat, invio di un messaggio sull'account di test.
Validi una consegna webhook e uno stato di riconnessione o checkpoint prima di passare la chiave alla Produzione.
crm-app · DevelopmentUsata da Codex
Scopedev-tests · 2 account
Chiavescoped Account API key
AccountAccount LinkedIn di test, casella Gmail di test
Webhooks1 endpoint · eventi message
crm-app · ProductionIntatta
Scopeuno per workspace
Chiavescoped keys, in your backend only
Accountgli account dei suoi utenti, tramite Hosted Auth
Troubleshooting

Errori frequenti e cosa significano

Che cosa si vede quando una voce MCP di Codex non è corretta, e come risolverla. Quasi sempre si tratta del file, del TOML, del livello di attendibilità o della chiave.
Il server non compare dopo aver modificato config.toml
codex mcp list non stampa nulla, oppure la voce manca all'interno di una sessione. SoluzioneRiavvii il client: il file viene letto all'avvio. Poi controlli CODEX_HOME: sposta l'intera cartella di configurazione, quindi un server salvato in un terminale può risultare invisibile in un altro. Esegua codex mcp list nella stessa shell da cui avvia Codex.
La configurazione di progetto viene ignorata
.codex/config.toml si trova nella radice del repository, e Codex continua a usare la voce globale, o nessuna. SoluzioneCodex carica il livello di progetto solo per un progetto attendibile. Lo marchi con trust_level = "trusted" sotto [projects."/path/to/repo"] nella configurazione utente, oppure sposti la voce in ~/.codex/config.toml.
TOML non valido
Il file non viene interpretato e tutti i server spariscono insieme. SoluzioneUna tabella chiamata esattamente [mcp_servers.unipile] , le virgolette attorno a "X-API-KEY" nella tabella degli header, e una tabella, non una stringa, per http_headers. Una parentesi graffa non chiusa fa cadere l'intero file.
401 Unauthorized sulle richieste
Il server è elencato e legge la specifica, ma l'esecuzione di una richiesta fallisce. SoluzioneL'header manca, la variabile indicata in env_http_headers non è esportata nella shell che ha avviato Codex, oppure la chiave è una chiave Service o Account globale invece di una chiave API Account scoped della sua applicazione Development.
Le impostazioni dicono che il server non è disponibile
L'estensione per l'IDE o l'app desktop segnala il server, eppure le azioni funzionano. SoluzioneQuel controllo cerca risorse, e il server Unipile espone azioni, non risorse. Lo confermi con /mcp all'interno di una sessione ed eseguendo una chiamata di lettura. Non c'è nulla da cambiare da parte sua.
Timed out
L'avvio o una chiamata supera il limite. SoluzioneI valori predefiniti sono startup_timeout_sec = 10 e tool_timeout_sec = 60. Il server è remoto e non c'è alcun processo da avviare: controlli l'URL (?branch=v2.0 incluso), la rete ed eventuali proxy aziendali prima di aumentare i timeout.
6000+ Aziende che innovano con Unipile
Fiducia da parte dei leader del settore
1 API
Semplificare le operazioni per tutti i principali canali di comunicazione
2 giorni
Integrazione rapida con una configurazione minima
30%
Riduzione dell'impegno e delle risorse per la manutenzione

Sicurezza e conformità integrate

Protezione di livello aziendale per i vostri dati e flussi di lavoro Per saperne di più sulla nostra sicurezza
SOC 2 Tipo II
SOC 2 Tipo II
Certificato
Controlli di sicurezza verificati in modo indipendente che garantiscono la protezione dei dati e l'integrità operativa.
GDPR
GDPR
Conforme
Piena conformità alle normative europee sulla protezione dei dati per la privacy degli utenti.
99.9%
Uptime della piattaforma negli ultimi 24 mesi
24/7
Supporto globale con API ad alte prestazioni

FAQ server MCP Codex

Le domande che si pongono davvero: config.toml invece di mcp.json, dove si trova, codex mcp add, come tenere la chiave fuori dal file, le tre superfici, cosa controllare quando non compare nulla, timeout e chiavi.
No. Codex salva la sua configurazione MCP in ~/.codex/config.toml, in TOML, con una tabella per server chiamata [mcp_servers.<name>]. In Codex non esiste alcun mcp.json, e il file non viene creato all'installazione: lo crea lei, oppure lo crea codex mcp add per lei. Un progetto attendibile può anche avere un .codex/config.toml nella propria radice.
~/.codex/config.toml per la configurazione utente, .codex/config.toml nella radice del repository per la configurazione di progetto. La variabile d'ambiente CODEX_HOME sposta l'intera cartella di configurazione: quando un server compare in un terminale e non in un altro, la controlli per prima. Codex CLI, l'estensione per l'IDE e l'app desktop leggono lo stesso file.
In parte. codex mcp add unipile --url "https://developer.unipile.com/mcp?branch=v2.0" scrive la tabella per un server streamable HTTP, e --bearer-token-env-var copre i server che accettano un token Bearer. Il server Unipile si autentica con un header X-API-KEY , che il comando non può impostare, quindi aggiunge http_headers o env_http_headers alla voce che ha creato. Verificato su codex-cli 0.154.0.
Usare env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" }: associa il nome dell'header al nome di una variabile d'ambiente invece che a un valore, così il file può essere committato senza segreti e ogni sviluppatore esporta la propria chiave API Account scoped. http_headers serve per i valori statici, e http_headers_helper permette a un comando locale di produrre gli header in JSON.
Sì. Le tre superfici di uno stesso host Codex leggono la stessa configurazione, quindi un server aggiunto una volta è disponibile ovunque. Nell'app desktop e nell'estensione può anche aggiungerlo da Settings, MCP servers, Add server, scegliendo Streamable HTTP. Riavvii il client dopo aver salvato il file.
Quattro cause, in ordine: il client non è stato riavviato; il file si trova sotto un CODEX_HOME diverso da quello della shell corrente; la tabella è in un .codex/config.toml di progetto e il progetto non è marcato trust_level = "trusted", nel qual caso Codex salta del tutto il livello di progetto; oppure il TOML non è valido. Esegua codex mcp list, poi /mcp all'interno di una sessione.
startup_timeout_sec sostituisce il timeout di avvio predefinito di 10 secondi e tool_timeout_sec quello per tool di 60 secondi, entrambi sotto la tabella del server. Il server Unipile è remoto su HTTP e non ha alcun processo locale da avviare, quindi un timeout di avvio indica quasi sempre l'URL, la rete o un proxy aziendale, non il server.
Il server risponde senza chiave quando l'agente si limita a leggere la specifica dell'API. Per eseguire richieste reali, crei uno Scope nella sua applicazione Development, vi assegni gli account di test e generi una chiave API Account scoped per quello Scope. Non dia mai a un client MCP una chiave Service o una chiave Account globale.