# Il server MCP di Nodary

Nodary mette a disposizione un server MCP remoto, così un agente IA legge e scrive nel tuo spazio di lavoro come farebbe un collega: stessi documenti, stessi permessi, con l’accesso a tuo nome.

## In breve

- **Indirizzo**: https://nodary.ai/api/mcp
- **Trasporto**: Streamable HTTP (JSON-RPC via POST)
- **Autenticazione**: OAuth 2.1 con registrazione dinamica del client e PKCE, oppure una chiave API
- **Accesso**: Incluso in tutti i piani; nel piano Free, entro i limiti del piano
- **Rilevamento**: https://nodary.ai/.well-known/oauth-protected-resource/api/mcp · https://nodary.ai/.well-known/mcp.json

Claude Code: Esegui questo comando in un terminale (aggiungi --scope user per usare Nodary in tutti i progetti):

```sh
claude mcp add --transport http nodary https://nodary.ai/api/mcp
```

## Che cos’è

Il Model Context Protocol (MCP) è lo standard aperto con cui i client IA lavorano con strumenti esterni. Il server di Nodary dà a un agente lo stesso spazio di lavoro che usa il tuo team: progetti, documenti e i loro collegamenti, fogli di calcolo, immagini, tabelle di traduzione, dialoghi e board.

Un agente non riceve una copia. Legge ciò che c’è in quel momento, scrive dove glielo chiedi e ogni risultato riporta il link che una persona può aprire per verificarne il lavoro.

## Come si accede

La maggior parte dei client accede con OAuth: basta indicare l’indirizzo del server e il client apre nel browser una pagina Nodary di accesso e consenso. Nodary supporta OAuth 2.1 con registrazione dinamica del client e PKCE, quindi non c’è nessun client ID da creare e niente da copiare. I token di accesso durano un’ora e il client li rinnova.

Una sola connessione può raggiungere più spazi di lavoro. Se fai parte di più spazi, la pagina di consenso li elenca tutti, spuntati: l’app raggiunge allora gli spazi che lasci spuntati, e solo quelli. «Anche gli spazi in cui entrerò più avanti» resta disattivato finché non lo spunti. In una connessione così, ogni strumento accetta workspace (id, slug o nome): una chiamata che modifica qualcosa deve indicarlo, una lettura senza di esso funziona solo dove si trovano i suoi id, e ogni risultato inizia con lo spazio in cui è stato eseguito. Una chiave API resta legata a un solo spazio.

Un client che non riesce ad accedere può usare invece una chiave API: creane una nel tuo profilo, alla voce API keys & MCP (inizia con gdc_), e inviala nell’intestazione Authorization: Bearer gdc_… Una chiave può essere limitata a un solo progetto.

## Chi può usarlo

Il server MCP è incluso in tutti i piani, Free, Pro, Studio ed Enterprise, per ogni membro e senza costi aggiuntivi.

Nel piano Free, un agente legge e scrive come in un piano a pagamento finché lo spazio di lavoro resta entro il piano: 1 progetto, 10 documenti e cartelle, e 2 membri. Una scrittura che supererebbe un limite viene rifiutata indicando il limite raggiunto e come superarlo: finché lo spazio può ancora avere la sua prova, il link alla dashboard, dove il proprietario o un amministratore avvia la prova di Studio di 14 giorni (con MCP, senza carta); altrimenti il link alla pagina dei prezzi.

Uno spazio di lavoro oltre il piano Free dopo la prova, senza abbonamento, è bloccato finché non si abbona: lì gli agenti sono disattivati, lettura compresa. Una connessione a quel solo spazio riceve quota_locked a ogni richiesta, con ciò che supera il piano e dove il proprietario si abbona; una connessione a più spazi riceve quota_locked (o billing_locked dopo un pagamento non riuscito) solo sulle chiamate verso lo spazio bloccato, come errore dello strumento, e continua a funzionare negli altri.

- [Prezzi](https://nodary.ai/it/pricing)

## Cosa può fare un agente

92 strumenti, raggruppati qui in base al lavoro che svolgono. Ognuno indica al client se si limita a leggere e se una scrittura può sovrascrivere qualcosa, così il client può chiederti conferma prima di agire.

### Trovare e leggere

Progetti, documenti con i loro collegamenti e la loro cronologia, commenti, note di conoscenza, viste salvate e brief di contesto. I risultati riportano link che le persone possono aprire.

`list_games`, `list_stars`, `search_documents`, `get_document`, `get_star`, `get_tree`, `list_templates`, `list_members`, `list_project_knowledge`, `get_project_knowledge`, `list_comments`, `get_canon`, `list_versions`, `get_version`, `diff_versions`, `list_deleted_stars`, `list_context_briefs`, `get_context_brief`, `list_saved_views`, `get_saved_view`, `list_favorites`, `get_workspace_usage`, `list_properties`, `get_file_url`, `describe_blocks`, `run_view`, `list_workspaces`

### Scrivere e organizzare

Creare e modificare documenti blocco per blocco, archiviarli in cartelle, collegarli, assegnare tag, commentare, impostare proprietà e risolvere le contraddizioni. Un documento eliminato può essere ripristinato.

`create_game`, `update_game`, `rename_workspace`, `create_starter_constellation`, `create_from_template`, `create_star`, `create_stars`, `write_document`, `append_document`, `edit_document`, `update_star`, `update_stars`, `delete_star`, `restore_star`, `create_cluster`, `move_to_cluster`, `link_stars`, `unlink_stars`, `set_tags`, `save_project_knowledge`, `add_comment`, `add_comments`, `resolve_comment`, `list_contradictions`, `report_contradiction`, `resolve_contradiction`, `save_context_brief`, `save_saved_view`, `set_favorite`, `define_properties`, `set_properties`, `restore_version`, `edit_comment`, `delete_comment`, `delete_project_knowledge`, `remove_context_brief`, `remove_saved_view`, `open_daily_note`

### Revisione artistica e immagini

Importare immagini, esaminarle con le note che le persone vi hanno disegnato sopra, decidere, annotare e taggare le consegne (ogni decisione firmata con chi e quando), trasformare un moodboard in una palette e confrontarci un’immagine, e preparare la scheda di feedback per un outsourcer.

`add_image`, `start_upload`, `add_media`, `get_image`, `get_moodboard`, `render_board`, `edit_board`, `find_pictures`, `update_pictures`, `get_art_review`, `extract_palette`, `check_palette`, `feedback_sheet`, `restore_image_version`, `set_image_origin`

### Fogli di calcolo e bilanciamento

Leggere un foglio come valori calcolati, con la formula dietro ogni cella, scrivere celle per indirizzo o per riga, e leggere una tabella del bottino per capire cosa significa per i giocatori.

`get_sheet`, `set_cells`, `analyze_drops`

### Localizzazione e dialoghi

Vedere l’avanzamento di ogni lingua in una tabella di traduzione, scrivere traduzioni per chiave e verificare un dialogo ramificato, che si esporta come script Yarn Spinner.

`get_localization`, `set_translations`, `check_dialogue`

### Produzione

Impostare scadenze, richiedere e inviare revisioni, vedere cosa è cambiato di recente e se la milestone verrà rispettata.

`get_progress`, `recent_changes`, `set_due_date`, `set_due_dates`, `request_review`, `submit_review`

## Prompt e risorse

Richieste già pronte che un client può proporre come comandi:

- weekly-summary: Cosa è cambiato questa settimana nello spazio di lavoro o in un progetto: cosa è stato scritto, deciso, revisionato e cosa resta aperto.
- art-review: A che punto è la revisione artistica: le immagini in attesa di una decisione, quelle che si allontanano dalla palette e cosa decidere dopo.
- playtest-to-tasks: Trasforma le note di playtest in attività, ognuna collegata al documento di design che riguarda.
- balance-review: Legge una tabella del bottino o una curva di progressione e spiega cosa significa per i giocatori e cosa non torna.

Risorse che un client può allegare senza chiamare uno strumento:

- nodary://star/{id}: un documento, in Markdown
- nodary://project/{id}: la struttura di un progetto

## Sicurezza

- Un agente agisce come la persona che lo ha collegato: vede e modifica solo ciò che può vedere e modificare quella persona, e una chiave limitata a un progetto resta in quel progetto.
- In una connessione a più spazi di lavoro nulla si risolve da uno spazio all’altro: id e titoli si cercano solo nello spazio indicato dalla chiamata, un id di un altro spazio viene rifiutato prima di eseguire qualsiasi cosa, e ogni risultato indica il suo spazio.
- I documenti conservano la cronologia delle versioni e un documento eliminato può essere ripristinato.
- Gli strumenti di scrittura accettano una chiave di idempotenza: una chiamata ripetuta dopo una connessione interrotta restituisce il primo risultato invece di scrivere due volte.
- Una connessione fa al massimo 120 richieste al minuto; la scrittura non ha un limite giornaliero.
- Le decisioni della revisione artistica sono firmate con il nome di chi le ha prese e l’ora.
- Nodary indica a ogni agente che il testo dei documenti e dei commenti è materiale su cui lavorare, non istruzioni da seguire. Come l’agente si comporta di conseguenza dipende dall’agente stesso.

## Collega il tuo client

Usa l’indirizzo https://nodary.ai/api/mcp. Ogni client qui sotto è stato verificato sulla sua documentazione il 1° ottobre 2026.

### Claude (claude.ai e Claude Desktop)

1. Apri Customize, poi Connectors, e scegli Add custom connector.
2. Inserisci https://nodary.ai/api/mcp. Quando Claude chiede come eseguire la registrazione, scegli Register automatically.
3. Avvia il collegamento, accedi a Nodary e approva l’accesso.

I connettori personalizzati sono disponibili sui piani Free, Pro, Max, Team ed Enterprise; anche un account Free può aggiungerne uno. Su Team ed Enterprise, prima un proprietario deve aggiungere il connettore per l’organizzazione.

### ChatGPT

1. In Settings, alla voce Security and login, attiva Developer mode.
2. Crea un’app per un server MCP remoto con l’indirizzo https://nodary.ai/api/mcp e l’accesso OAuth.
3. Accedi a Nodary e approva l’accesso. Gli strumenti compaiono poi nel campo di composizione, in Developer mode.

La Developer mode è disponibile sul web per gli account Plus, Pro, Business, Enterprise ed Education; su Business ed Enterprise potrebbe servire l’autorizzazione di un amministratore. ChatGPT si collega solo con OAuth, non con una chiave API.

### Claude Code

1. Esegui questo comando in un terminale (aggiungi --scope user per usare Nodary in tutti i progetti):

   ```
   claude mcp add --transport http nodary https://nodary.ai/api/mcp
   ```
2. In Claude Code, digita /mcp, scegli nodary e accedi dal browser.

Con una chiave API

```sh
claude mcp add --transport http nodary https://nodary.ai/api/mcp \
  --header "Authorization: Bearer gdc_..."
```

### Cursor

1. Aggiungi Nodary a ~/.cursor/mcp.json (tutti i progetti) o a .cursor/mcp.json (un solo progetto):

   ```
   {
     "mcpServers": {
       "nodary": {
         "url": "https://nodary.ai/api/mcp"
       }
     }
   }
   ```
2. Cursor propone di accedere la prima volta che il server lo richiede.

Con una chiave API

```json
{
  "mcpServers": {
    "nodary": {
      "url": "https://nodary.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NODARY_API_KEY}"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

1. Aggiungi Nodary a .vscode/mcp.json nella tua area di lavoro, oppure esegui il comando MCP: Add Server:

   ```
   {
     "servers": {
       "nodary": {
         "type": "http",
         "url": "https://nodary.ai/api/mcp"
       }
     }
   }
   ```
2. Avvia il server; VS Code apre la pagina di accesso a Nodary.

Su Copilot Business ed Enterprise, un amministratore deve prima autorizzare i server MCP.

Con una chiave API

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "nodary-key",
      "description": "Nodary API key",
      "password": true
    }
  ],
  "servers": {
    "nodary": {
      "type": "http",
      "url": "https://nodary.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:nodary-key}"
      }
    }
  }
}
```

### Devin Desktop (in precedenza Windsurf)

1. Aggiungi il server ed esegui l’accesso da un terminale:

   ```
   devin mcp add -s user nodary https://nodary.ai/api/mcp
   devin mcp login nodary
   ```
2. Oppure aggiungilo a ~/.config/devin/mcp_config.json (su Windows, %APPDATA%\devin\mcp_config.json):

   ```
   {
     "mcpServers": {
       "nodary": {
         "url": "https://nodary.ai/api/mcp",
         "transport": "http"
       }
     }
   }
   ```

## Se qualcosa non funziona

- Una prima richiesta che riceve un 401 con un indirizzo resource_metadata è normale: indica al client dove accedere.
- Una richiesta rifiutata con quota_locked significa che lo spazio di lavoro supera il piano Free dopo la prova ed è bloccato finché non si abbona: appena il proprietario si abbona, l’agente torna a funzionare. In una connessione a più spazi, vengono rifiutate solo le chiamate verso quello spazio.
- Una chiamata rifiutata con workspace_required (o workspace_not_found) elenca gli spazi raggiunti dalla connessione: passane uno come workspace. Per raggiungere uno spazio che non è nell’elenco, collega di nuovo l’app e spuntalo.
- Se un client non riesce a completare l’accesso, collegalo con una chiave API.

https://nodary.ai/it/docs/mcp