Conectar um assistente de IA

Um assistente de IA pode ler seus números e responder em linguagem comum: "Quanto eu ganhei líquido no mês passado?", "Qual livro me custa mais em anúncios?".

Ele só pode ler. O assistente vê o que a API do TrueRoyalties vê — royalties, gastos com anúncios, lucro líquido, livros, séries, Kindle Unlimited — e não altera nada na sua conta.

O que o assistente pode ver

• Tudo o que a API vê, e nada mais: royalties, gastos com anúncios, lucro líquido, livros, séries, páginas do Kindle Unlimited, downloads gratuitos.
• Nada que ele possa alterar: nenhuma sincronização, nenhuma configuração, nenhum livro, nenhuma cobrança.
• Seus números saem mesmo do TrueRoyalties. Conecte só um assistente em quem você confia seu histórico de vendas: depois que ele leu seus números, desconectar impede novas leituras, mas não recupera o que já foi lido.

O endereço, e o que cada assistente precisa

Um endereço só, o mesmo para todos os assistentes:

https://author.trueroyalties.com/api/mcp

Qualquer outra ferramenta que aceite servidores MCP personalizados pode usar o mesmo endereço.

Está tudo numa página só do app — Configurações → API: o endereço, os comandos prontos para colar e suas chaves. Cada bloco tem um botão Copiar.

claude.ai

1. No claude.ai, abra Customize no menu esquerdo.

2. Abra a aba Connectors.

3. Clique em Add e depois em Add custom connector.

4. Dê o nome TrueRoyalties, cole https://author.trueroyalties.com/api/mcp e clique em Continue.

5. Não mexa em nada na página seguinte: o claude.ai detectou que o TrueRoyalties faz você entrar e publica a própria identidade. Clique em Add.

6. Clique em Connect.

7. Entre no TrueRoyalties se for pedido.
8. Confira qual app está pedindo acesso e clique em Permitir.

9. Você volta ao claude.ai. Na página do conector, em Tool permissions, escolha Always allow: o Claude passa a ler seus números sem perguntar toda vez, e este conector não sabe fazer mais nada.

Numa conversa, ative o conector se o app pedir, e faça sua pergunta.

Pergunte ao Haiku. É o modelo Claude mais rápido e mais barato, e ler seus números não exige mais do que isso. Escolha-o no menu de modelos da conversa.

Uma conta gratuita do Claude pode adicionar um conector personalizado.

Para desconectar, abra Configurações → API → Apps conectados no TrueRoyalties e escolha Desconectar. Ele para de ler seus números na hora.

Claude Desktop

O Claude Desktop usa os mesmos conectores do claude.ai, então não há mais nada para instalar: adicione o conector em qualquer um dos dois, entre e clique em Permitir. Depois ele funciona nos dois.

ChatGPT

O ChatGPT não se conecta como o Claude: os servidores personalizados ficam atrás do modo desenvolvedor, oferecido só nos planos pagos. Este é o caminho completo.

1. Nas configurações do ChatGPT, ative o modo desenvolvedor.
2. Abra Plugins e depois New plugin.
3. Name: digite TrueRoyalties. O ícone e a descrição são opcionais.
4. Connection: deixe Server URL e cole https://author.trueroyalties.com/api/mcp.
5. Authentication: escolha OAuth. Não há nada para preencher abaixo — o TrueRoyalties publica suas configurações nesse endereço e o ChatGPT as lê.
6. Marque I understand and want to continue — o ChatGPT mostra esse aviso para qualquer servidor personalizado, inclusive o nosso — e clique em Create.

7. O ChatGPT abre o TrueRoyalties: entre se for pedido, confira que o app pedindo acesso é o ChatGPT e clique em Permitir.
8. Numa conversa, ative o plugin antes da sua primeira pergunta.
9. Escolha o que o ChatGPT pode fazer sozinho, em Settings → Plugins → TrueRoyalties → Permissions. Allow read actions basta: este conector só sabe ler. Allow all actions está marcado como risco elevado e aqui não traz nada.

Para desconectar, abra Configurações → API → Apps conectados no TrueRoyalties e escolha Desconectar, exatamente como no claude.ai.

Claude Code

Crie uma chave em Configurações → API → Criar uma chave, dê o nome "Claude Code" e copie. Ela é mostrada uma única vez.

Depois rode isto num terminal, com sua chave no lugar de YOUR_API_KEY:

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

• Confira com claude mcp list, ou /mcp dentro do Claude Code.
• O servidor é adicionado ao projeto atual. Acrescente --scope user para usá-lo em todos.
• Para remover: claude mcp remove trueroyalties.

Cursor

Coloque sua chave na variável de ambiente TRUEROYALTIES_API_KEY e cole isto em ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto):

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

O Cursor lê a chave dessa variável, então o arquivo nunca a contém. Defina a variável antes de abrir o Cursor.

VS Code

Abra MCP: Open User Configuration na paleta de comandos (todos os projetos), ou crie .vscode/mcp.json num projeto, e adicione:

{
  "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}"
      }
    }
  }
}

O VS Code pede a chave na primeira vez que o servidor inicia e a guarda, então o arquivo nunca a contém.

O que você pode perguntar

O assistente escolhe a ferramenta certa para a sua pergunta. Cada ferramenta lê uma parte da API.

Bom saber

• Os mesmos números do app. Cada resposta diz o período e a moeda usados, e avisa quando um número está incompleto.
• Uma chave lê toda a sua conta. Mantenha-a fora de arquivos compartilhados e revogue-a em Configurações → API no dia em que parar de usar o assistente.
• Limites compartilhados com a API: 60 requisições por minuto e 10.000 por dia para sua conta. Uma pergunta pode custar várias requisições. Veja Limites e erros.
• Experimente sem conta numa ferramenta para desenvolvedores: a chave de demonstração pública da referência da API funciona aqui também e lê os números fictícios da conta de demonstração.