Collega un assistente IA

Chiedi a claude.ai, ChatGPT, Claude Code, Cursor, VS Code o Claude Desktop delle tue royalty, della spesa pubblicitaria e del profitto netto. Il server MCP di TrueRoyalties si collega con un accesso o con la tua chiave API, e legge gli stessi numeri dell'API.

Il server MCP di TrueRoyalties permette a un assistente IA di leggere i tuoi numeri e rispondere a domande in linguaggio normale: «Quanto ho guadagnato netto il mese scorso?», «Quale libro mi costa di più in pubblicità?». MCP (Model Context Protocol) è lo standard che questi assistenti usano per collegarsi a strumenti esterni.

È in sola lettura: l'assistente vede esattamente quello che vede l'API di TrueRoyalties, e non può modificare nulla. claude.ai e ChatGPT si collegano con un accesso. Gli strumenti per sviluppatori usano una chiave API.

L'indirizzo del server, per tutti gli assistenti: https://author.trueroyalties.com/api/mcp

claude.ai e ChatGPT

In claude.ai, apri Customize → Connectors → Add custom connector. In ChatGPT, attiva la modalità sviluppatore, poi aggiungi un connettore.
Incolla https://author.trueroyalties.com/api/mcp e fai clic su Connect.
Accedi a TrueRoyalties se richiesto, controlla quale app chiede l'accesso, poi fai clic su Consenti.

La pagina di autorizzazione di TrueRoyalties, dove Claude chiede di leggere l'account, verificata come proveniente da claude.ai, con ciò che può e non può fare e i pulsanti per consentire o negare

Tornato nell'assistente, fai la tua domanda. A seconda dell'app, potresti dover attivare il connettore per una conversazione.

Nessuna chiave da copiare. L'assistente riceve un accesso tutto suo, che può solo leggere.
Scollegalo quando vuoi in Impostazioni → API → App collegate. Smette subito di leggere i tuoi numeri.
ChatGPT offre i connettori personalizzati solo in modalità sviluppatore, sui piani a pagamento. Un account Claude gratuito può aggiungere un connettore personalizzato.

Strumenti per sviluppatori

Claude Code, Cursor e VS Code usano una chiave API:


Una chiave API	Impostazioni → API → Crea una chiave. Dalle il nome dell'assistente, per esempio «Claude Code».
L'indirizzo del server	`https://author.trueroyalties.com/api/mcp`

La chiave legge tutto il tuo account. Quando lo strumento lo consente, tienila fuori dai file condivisi, e revocala in Impostazioni → API il giorno in cui smetti di usare l'assistente.

Claude Code

Esegui questo in un terminale, sostituendo YOUR_API_KEY con la tua chiave:

claude mcp add --transport http trueroyalties https://author.trueroyalties.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Controlla con claude mcp list, oppure con /mcp dentro Claude Code.
Il server viene aggiunto al progetto corrente. Aggiungi --scope user per usarlo in tutti i tuoi progetti.
Per rimuoverlo: claude mcp remove trueroyalties.

Cursor

Aggiungi il server in ~/.cursor/mcp.json (tutti i tuoi progetti) o in .cursor/mcp.json (un progetto):

{
  "mcpServers": {
    "trueroyalties": {
      "url": "https://author.trueroyalties.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TRUEROYALTIES_API_KEY}"
      }
    }
  }
}

Cursor legge la chiave dalla variabile d'ambiente TRUEROYALTIES_API_KEY, quindi il file non la contiene mai. Imposta questa variabile nel terminale prima di aprire Cursor.

VS Code

Apri MCP: Open User Configuration dalla tavolozza dei comandi (tutti i tuoi progetti), oppure crea .vscode/mcp.json in un progetto, e aggiungi:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "trueroyalties-api-key",
      "description": "TrueRoyalties API key",
      "password": true
    }
  ],
  "servers": {
    "trueroyalties": {
      "type": "http",
      "url": "https://author.trueroyalties.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:trueroyalties-api-key}"
      }
    }
  }
}

VS Code ti chiede la chiave al primo avvio del server e la conserva per te, quindi il file non la contiene mai.

Claude Desktop

Claude Desktop usa gli stessi connettori di claude.ai. Aggiungi il connettore come descritto in claude.ai e ChatGPT, da claude.ai o dalle impostazioni dei connettori di Claude Desktop, poi accedi e fai clic su Consenti.

Cosa puoi chiedere

L'assistente sceglie lo strumento giusto per la tua domanda. Ogni strumento legge una parte dell'API.

Strumento	Legge	Domanda di esempio
`get_account`	Il tuo account: valuta, abbonamento, piattaforme collegate	«Le mie piattaforme sono aggiornate?»
`list_books`	Il tuo catalogo	«Quali libri ho?»
`list_series`	Le tue serie e i loro libri	«Quali sono le mie serie?»
`get_summary`	I totali di un periodo	«Quanto ho guadagnato netto il mese scorso?»
`get_timeline`	Gli stessi numeri nel tempo	«Come è cambiato il mio profitto da gennaio?»
`get_books_report`	Una riga per libro	«Quale libro mi costa di più in pubblicità?»
`get_marketplaces_report`	Una riga per marketplace	«Dove vendo meglio?»
`get_kenp`	Le pagine lette su Kindle Unlimited	«Quante pagine KU sono state lette questo mese, e quante grazie alla pubblicità?»
`get_free_units`	I download gratuiti	«Quanti download gratuiti ha portato la mia promozione?»
`get_series_read_through`	La lettura di una serie	«Quanti lettori del libro 1 arrivano al libro 3?»

Buono a sapersi

Gli stessi numeri dell'app e dell'API. Ogni risposta indica il periodo e la valuta usati, e lo dice quando un numero è incompleto.
Gli stessi limiti dell'API, condivisi con essa: 60 richieste al minuto e 10.000 al giorno per il tuo account. Un assistente può fare più chiamate per una sola domanda. Vedi Limiti ed errori.
Provalo senza account in uno strumento per sviluppatori. La chiave demo pubblica mostrata nella reference dell'API funziona anche qui. Legge i numeri fittizi dell'account demo, non i tuoi.

Usare l'API da Google Sheets Perché i miei numeri sono diversi da Amazon