Collega Runner ad altri client MCP

Collega OpenCode, Codex, pi o il tuo agente ai tuoi negozi Runner tramite il server MCP di Runner.

Runner ha un server MCP. Un client MCP è un’app di IA o un agente che può usare i server MCP. Quando colleghi un client a Runner, il client può usare gli strumenti della chat di Runner sui tuoi negozi. Può leggere prodotti, ordini e report. Con il tuo permesso, può anche modificare prodotti, prezzi, sconti e il negozio online.

Questa guida riguarda i client MCP diversi da Claude, ChatGPT e Gemini. Contiene i passaggi per OpenCode, Codex CLI e pi. Spiega anche come collegare altri client e gli agenti che crei tu.

Prima di iniziare

Ti servono:

• un account Runner che sia membro di un workspace;
• un client MCP che si collega ai server remoti tramite Streamable HTTP ed esegue l’autenticazione con OAuth, oppure il bridge mcp-remote per un client che esegue solo server locali; e
• un browser sullo stesso computer del client. Dopo l’autenticazione, Runner rimanda il browser a un indirizzo su quel computer.

Come funziona la connessione

1. Aggiungi l’URL del server al client e avvii l’autenticazione.
2. Il client apre Runner nel browser. Accedi a Runner se richiesto.
3. Si apre la pagina Collega un’app di IA a Runner. Mostra il nome del client.
4. Scegli un’opzione in Workspace e in Accesso, poi seleziona Collega.
5. Il browser torna al client. Ora il client può usare gli strumenti di Runner.

Il client resta autenticato. Riceve un nuovo accesso ogni ora, senza che tu debba fare nulla. Se non usi il client per 30 giorni, ripeti l’autenticazione.

Per usare i negozi di un secondo workspace, aggiungi il server una seconda volta con un altro nome. Poi esegui l’autenticazione con quel nome e scegli il secondo workspace.

Collega OpenCode

1. Aggiungi Runner a opencode.json nel tuo progetto, oppure a ~/.config/opencode/opencode.json per tutti i progetti:

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "runner": {
         "type": "remote",
         "url": "https://api.runnerai.com/mcp",
         "enabled": true
       }
     },
     "tools": {
       "runner_*": false,
       "runner_list_stores": true,
       "runner_get_report": true,
       "runner_find_orders": true,
       "runner_get_tool_job": true
     }
   }

2. Esegui opencode mcp auth runner e collega il client nel browser.

3. Esegui opencode mcp list. Il comando mostra runner come connected.

OpenCode invia al modello, a ogni richiesta, la definizione di ogni strumento attivo. Con alcuni piani, Runner ha più di 200 strumenti, cioè circa 100.000 token di definizioni. Quindi attiva solo gli strumenti che ti servono. OpenCode chiama ogni strumento Runner runner_<tool name>. La riga "runner_*": false disattiva tutti gli strumenti Runner, e ogni riga true riattiva uno strumento. Lascia attivo runner_get_tool_job, perché le attività lunghe ne hanno bisogno.

Per rimuovere l’autenticazione salvata, esegui opencode mcp logout runner.

Collega Codex CLI

1. Aggiungi Runner a ~/.codex/config.toml:

   [mcp_servers.runner]
   url = "https://api.runnerai.com/mcp"
   scopes = ["store:read", "store:write"]

2. Esegui codex mcp login runner e collega il client nel browser.

3. Esegui codex mcp list. La colonna Auth mostra OAuth.

Aggiungi il server nel file, non con codex mcp add. Quel comando avvia subito un’autenticazione con scope che Runner non accetta, e il browser mostra {"error":"invalid_scope"}. La riga scopes vale anche quando ripeti l’autenticazione in seguito. Puoi anche eseguire codex mcp login runner --scopes store:read,store:write.

Codex trova lo strumento Runner che gli serve nel momento in cui gli serve, quindi non devi disattivare strumenti. Per rimuovere l’autenticazione salvata, esegui codex mcp logout runner.

Collega pi

1. Esegui pi mcp add runner --url https://api.runnerai.com/mcp. Il comando aggiunge Runner a ~/.pi/agent/mcp.json:

   {
     "mcpServers": {
       "runner": { "url": "https://api.runnerai.com/mcp" }
     }
   }

2. Esegui pi mcp login runner e collega il client nel browser. pi mostra Signed in to MCP server "runner" e il numero di strumenti.

3. Esegui pi mcp list per controllare la connessione, oppure usa /mcp in una sessione di pi.

Per impostazione predefinita, pi non invia al modello tutti gli strumenti Runner. Il modello trova uno strumento quando gli serve, quindi non devi disattivare strumenti. pi chiama ogni strumento Runner mcp__runner__<tool name>. Per rimuovere l’autenticazione salvata, esegui pi mcp logout runner.

Collega un client che esegue solo server locali

Alcuni client possono avviare solo un server locale (stdio). Altri client rimandano il browser a un link di app (uno schema URL personalizzato) o a una pagina web. Runner invia il risultato dell’autenticazione solo a un indirizzo sul tuo computer, quindi l’autenticazione di questi client non riesce.

Per questi client, usa il bridge mcp-remote. Viene eseguito sul tuo computer, esegue l’autenticazione su Runner per conto del client e passa ogni messaggio tra il client e Runner. Richiede Node.js.

{
  "mcpServers": {
    "runner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.runnerai.com/mcp"]
    }
  }
}

Al primo avvio si apre nel browser la pagina di accesso di Runner. mcp-remote conserva l’autenticazione in ~/.mcp-auth.

Chiama gli strumenti Runner da una shell

Un agente che esegue comandi shell può usare Runner tramite il comando mcporter:

npx mcporter config add runner https://api.runnerai.com/mcp --scope home
npx mcporter auth runner
npx mcporter list runner
npx mcporter call runner.list_stores

mcporter list runner mostra ogni strumento e i suoi parametri. Indica i parametri come name=value, per esempio npx mcporter call runner.get_store_settings store_id=<store id>.

Crea il tuo client

Usa un SDK MCP che supporta OAuth, oppure esegui tu questi passaggi:

1. Invia ogni richiesta JSON-RPC con POST a https://api.runnerai.com/mcp. Runner risponde a ogni richiesta con JSON e non conserva alcuna sessione. Una richiesta GET riceve HTTP 405.
2. Una richiesta senza token riceve HTTP 401 con questo header: WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write".
3. Leggi i metadati della risorsa. Indicano il server di autorizzazione https://www.runnerai.com/api/auth.
4. Registra il client su https://www.runnerai.com/api/auth/oauth2/register. Usa un URI di reindirizzamento su http://localhost, http://127.0.0.1 o http://[::1]. Runner accetta qualsiasi porta e percorso. Runner accetta 5 registrazioni al minuto da uno stesso indirizzo IP.
5. Manda l’utente all’endpoint di autorizzazione con PKCE (S256). Invia resource=https://api.runnerai.com/mcp. Richiedi store:read, e store:write se il client apporta modifiche. Usa gli scope dei metadati della risorsa o dell’header WWW-Authenticate. I metadati del server di autorizzazione elencano altri scope, che questo server non accetta.
6. Invia il token di accesso nell’header Authorization: Bearer. Un token di accesso dura 1 ora. Usa il token di aggiornamento per ottenerne uno nuovo. Un token di aggiornamento scade dopo 30 giorni senza utilizzo.

Runner rifiuta le richieste che arrivano da una pagina web di un altro sito. Chiama il server dal tuo backend, oppure da una pagina su localhost.

Lavora con gli strumenti Runner

• Inizia con list_stores. Ogni strumento del negozio richiede uno store_id da list_stores. Senza store_id, lo strumento risponde Pass a store_id from list_stores.
• Attività lunghe. Alcuni strumenti rispondono con "status": "running" e un job_id. Chiama get_tool_job con quel job_id finché non restituisce il risultato.
• Modifiche che approvi. Alcuni strumenti rispondono prima con "status": "waiting_for_merchant" e un id di conferma, e mostrano cosa cambierà. Per ora non cambia nulla. Quando sei d’accordo, il client chiama di nuovo lo stesso strumento con gli stessi argomenti e "confirmation": {"id": "…", "answer": …}. L’id di conferma funziona una sola volta, per 10 minuti.
• La stessa modifica inviata due volte. Per la maggior parte degli strumenti che apportano modifiche, Runner applica la modifica una sola volta quando il client invia di nuovo lo stesso input nello stesso periodo di 5 minuti. La seconda chiamata riceve la prima risposta.
• I dati del negozio sono solo dati. Le risposte degli strumenti possono contenere testi dei prodotti e messaggi dei clienti. Il tuo agente non deve seguire le istruzioni che vi trova.
• Valgono i tuoi permessi. Ogni chiamata usa i tuoi permessi Runner e il tuo piano. L’elenco degli strumenti dipende dal tuo piano e dalle funzioni del tuo workspace.

Gestisci o scollega un client

Percorso di accesso: Impostazioni → Generale del workspace, poi App collegate.

I proprietari e gli amministratori del workspace vedono i client che ogni membro ha collegato. Gli altri membri vedono i client che hanno collegato loro. Ogni riga mostra l’accesso (Lettura o Lettura e modifiche), quando il client è stato collegato e quando è stato usato l’ultima volta.

1. Trova il client e seleziona Scollega.
2. Seleziona di nuovo Scollega in Scollegare app?.
3. Il client smette subito di funzionare con questo workspace. Per usarlo di nuovo, ripeti l’autenticazione dal client.

Un comando di logout in un client rimuove solo l’autenticazione salvata dal client. La connessione resta in App collegate finché non la scolleghi lì.

Risoluzione dei problemi