---
lastModified: 2026-11-13
title: Collega Runner ad altri client MCP
description: Collega OpenCode, Codex, pi o il tuo agente ai tuoi negozi Runner tramite il server MCP di Runner.
seo:
  description: "Collega OpenCode, Codex, pi o il tuo agente ai tuoi negozi Runner. Aggiungi un URL del server, accedi a Runner nel browser e scegli cosa può fare il client."
---

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.

| Impostazione | Valore |
| --- | --- |
| URL del server | `https://api.runnerai.com/mcp` |
| Trasporto | Streamable HTTP. Runner non supporta il vecchio trasporto SSE. |
| Autenticazione | OAuth nel browser. Non ti serve una chiave API. |
| Accesso | `store:read` per leggere i dati del negozio. `store:write` per apportare modifiche. |

## 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.

| Controllo o messaggio | Perché è utile | Cosa succede dopo |
| --- | --- | --- |
| **Torna a** | Mostra l’indirizzo sul tuo computer che riceve il risultato dell’autenticazione. | Mostra `localhost`, `127.0.0.1` o `[::1]` e un numero di porta. |
| **Runner non può confermare di quale app si tratti. Collegala solo se hai avviato tu questa connessione.** | Runner non può verificare l’identità di un client che hai installato o creato. | Collega il client solo se hai avviato tu l’autenticazione dal tuo client. |
| **Workspace** | Una connessione funziona con i negozi di un solo workspace. | Il client può usare solo i negozi del workspace che scegli. |
| **Lettura** | Sempre attivo. Il client può vedere i dati del negozio, come prodotti, ordini e report. | Non puoi disattivarlo. |
| **Apportare modifiche** | Permette al client di modificare i dati del negozio, come prodotti, prezzi e sconti. | All’inizio è disattivato. Compare solo se il client chiede l’accesso per apportare modifiche. |
| **Collega** | Dà al client l’accesso che hai scelto. | Il browser torna al client. |
| **Annulla** | Interrompe l’autenticazione. | Il client non riceve alcun accesso. |

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:

   ```json
   {
     "$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`:

   ```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`:

   ```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.

```json
{
  "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`:

```bash
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

| Cosa vedi | Causa | Cosa fare |
| --- | --- | --- |
| `{"error":"invalid_scope"}` nel browser | Il client ha richiesto scope che questo server non accetta. `codex mcp add` lo fa. | Richiedi `store:read` e `store:write`. Per Codex, aggiungi la riga `scopes` ed esegui `codex mcp login runner`. |
| **This redirect URI cannot receive Merchant MCP codes.** | Il client rimanda il browser a un link di app o a una pagina web. | Usa il bridge `mcp-remote`. |
| **Request the Merchant MCP resource alone.** | Il client non ha inviato `resource=https://api.runnerai.com/mcp`. | Aggiorna il client, oppure usa il bridge `mcp-remote`. |
| **Questa richiesta di connessione non è disponibile. Riavvia la connessione dalla tua app di IA.** | Il link di autenticazione è vecchio o è già stato usato. | Riavvia l’autenticazione dal client. |
| **Non sei membro di alcun workspace. Crea un workspace in Runner, poi riavvia la connessione.** | Il tuo account non ha alcun workspace. | Crea un workspace, poi riavvia l’autenticazione. |
| **This tool needs store\:write. Reconnect Runner and allow changes to the store.** | La connessione ha solo l’accesso **Lettura**. | Esegui il logout nel client, ripeti l’autenticazione e attiva **Apportare modifiche**. |
| **This feature is not on for this store yet.** | La funzione non è attiva per il tuo piano, il tuo workspace o il tuo negozio. | Svolgi l’attività in Runner, oppure chiedi all’assistenza Runner. |
| Il provider del modello rifiuta la richiesta: `input_schema does not support oneOf, allOf, or anyOf at the top level` | Il client invia al modello tutti gli strumenti, e tre strumenti print-on-demand hanno uno schema che alcuni provider di modelli rifiutano. | Disattiva `publish_pod_product`, `review_pod_product` e `update_pod_product`, oppure attiva solo gli strumenti che ti servono. |
| Il client ti chiede di ripetere l’autenticazione | Hai scollegato il client in Runner, oppure non lo hai usato per 30 giorni. | Ripeti l’autenticazione dal client. |
| HTTP 429 quando il client si registra | Più di 5 registrazioni in un minuto da uno stesso indirizzo IP. | Attendi un minuto, poi riprova. |
| Una risposta termina con **Support reference:** e un codice | Lo strumento ha avuto un errore in Runner. | Comunica il codice all’assistenza Runner. |