Cursor è un editor di codice: l'SMS parte dal codice server della tua app, non da Cursor. Metti una chiave Telmian nel file .env del progetto, chiama POST https://app.telmian.com/v1/verify da una route server e controlla il codice con /v1/verify/check. Se vuoi, collega a Cursor il server MCP di Telmian per farti aiutare mentre sviluppi.
| Cosa | Dove |
|---|---|
| Chiave sandbox (sk_test_) | Il file .env del progetto, ignorato da Cursor per impostazione predefinita |
| Chiave live (sk_live_) | Le variabili d'ambiente dell'host che fa girare la tua app |
| Chiave per i Cloud Agents di Cursor | Dashboard, Cloud Agents, Secrets, come Runtime Secret |
| Server MCP di Telmian | Solo l'URL in .cursor/mcp.json; l'accesso avviene nel browser |
| Chiamate all'API Telmian | Solo codice lato server, mai componenti client |
Prendi una chiave sandbox gratuita
Apri il terminale di Cursor nel tuo progetto e lancia il comando qui sotto. Scrive una chiave sandbox (sk_test_) nel file .env. Non serve la carta e gli SMS in sandbox sono simulati.
npx telmian@1 initTieni la chiave fuori dalla chat e da git
Cursor ignora i file .env per impostazione predefinita, quindi le funzioni dell'Agent e le @-menzioni non leggono la chiave. Il terminale e gli strumenti MCP usati dall'Agent però non sono bloccati dai file di esclusione, quindi non è una garanzia. Controlla che .env sia nel tuo .gitignore. Non incollare mai la chiave in chat o nel codice client.
Facoltativo: collega il server MCP di Telmian
Cursor supporta i server MCP remoti. Aggiungi questo file come .cursor/mcp.json (un progetto) o ~/.cursor/mcp.json (tutti i progetti), poi attiva il server da Customize nella barra laterale. Se Cursor apre il browser, accedi a Telmian; il file non contiene chiavi, e gli invii reali a pagamento dall'AI restano spenti finché non li spunti al consenso.
{ "mcpServers": { "telmian": { "url": "https://app.telmian.com/mcp" } } }Aggiungi una regola di progetto
Una regola dice all'Agent come usare Telmian ogni volta. Salvala come .cursor/rules/telmian.mdc, oppure metti le stesse righe in AGENTS.md nella cartella principale del progetto.
--- description: Telmian SMS rules alwaysApply: true --- - Call Telmian (https://app.telmian.com/v1 or the telmian npm package) only from server-side code. - Read TELMIAN_API_KEY from the environment. Never put it in client code or mcp.json. - Use POST /v1/verify and POST /v1/verify/check for login codes. Do not generate codes yourself. - Send an Idempotency-Key on every POST that sends. Retry only with the same key. - In development use +393000000001 (code 000000) and +393000000002 (always fails).Scrivi il codice server
È il tuo progetto a decidere dove gira il codice server: una route handler di Next.js, un server Express o una Supabase Edge Function. Lì metti un endpoint che invia il codice e uno che lo controlla, mai nel browser.
// Server-side only. Never ship this to the browser. const TELMIAN_API_KEY = process.env.TELMIAN_API_KEY; const res = await fetch('https://app.telmian.com/v1/verify', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': signupAttemptId }, body: JSON.stringify({ phone }) }); const check = await fetch('https://app.telmian.com/v1/verify/check', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ phone, code }) }); const { valid } = await check.json();Prova con i numeri della sandbox
Invia un codice a +393000000001 e controllalo con 000000: devi ricevere {"valid":true}. Poi prova +393000000002 per vedere come la tua app gestisce un invio fallito.
Passa al live
Ricarica con carta da 5 € nel pannello su https://app.telmian.com, crea lì una chiave sk_live_ e impostala come TELMIAN_API_KEY sull'host che fa girare la tua app. Per i codici di verifica reali serve anche un nome aziendale approvato, da impostare nel pannello o con lo strumento MCP set_sender_profile. Se usi i Cloud Agents di Cursor, salva la chiave come Runtime Secret, non come Environment Variable.
Domande
Mi serve un telefono o una SIM mia, e quanto costa?
No, non ti serve un telefono né una SIM. Telmian invia dai propri numeri mobili europei. Costa 0,05 € per segmento SMS verso numeri mobili in 44 Paesi europei, più IVA, con ricarica prepagata da 5 € e nessun canone mensile. Gli SMS rifiutati dalla rete o non consegnati vengono rimborsati in automatico.
L'Agent di Cursor può vedere la mia chiave API?
Cursor ignora i file .env per impostazione predefinita, quindi l'Agent e le @-menzioni non li leggono. La documentazione di Cursor dice però che il terminale e gli strumenti MCP usati dall'Agent non sono bloccati dai file di esclusione, quindi la protezione non è garantita. Non incollare la chiave in chat.
Devo mettere la chiave API di Telmian in mcp.json?
No. Il server MCP di Telmian usa l'accesso dal browser, quindi in .cursor/mcp.json basta l'URL. Per questo puoi anche fare commit del file e condividere la configurazione con il tuo team.
La mia app usa Supabase Auth. Funziona lo stesso?
Sì. Telmian funziona come Send SMS hook di Supabase via HTTPS, e Supabase continua a creare e controllare i codici. Lo strumento MCP setup_supabase_sms ti restituisce URL e secret dell'hook. L'hook lo imposti in Supabase; Cursor modifica solo il tuo codice.
Dove arrivano le conferme di consegna e le risposte?
A un endpoint webhook nel tuo backend pubblicato, perché Cursor non ospita app. I webhook sono firmati: controllali con verifyWebhook dell'SDK telmian prima di fidarti.
Aggiornata il