Servidor MCP do Invoiso

O Invoiso fala o Model Context Protocol, por isso um cliente MCP — Claude, ChatGPT ou qualquer outro que o fale — consegue ler e trabalhar com as faturas, as despesas, os contactos, o stock e os relatórios do seu espaço invoiso. Esta página é o que precisa para ligar um.

O endpoint

https://www.invoiso.com/api/mcp

Transport   Streamable HTTP (POST, JSON-RPC 2.0)
Auth        OAuth 2.1 — see below
Server      invoiso 0.1.0
Protocol    2025-06-18, 2025-03-26, 2024-11-05

À maioria das pessoas basta o URL. Adicione-o como conector personalizado no ChatGPT ou como servidor MCP remoto no Claude e depois inicie sessão no invoiso como sempre — não é preciso qualquer chave de API. O cliente descobre sozinho como se autenticar: uma chamada não autenticada responde 401 com um cabeçalho WWW-Authenticate a apontar para https://www.invoiso.com/.well-known/oauth-protected-resource, onde constam o servidor de autorização e os âmbitos a pedir.

Ligar

1. Adicione https://www.invoiso.com/api/mcp ao seu cliente como servidor MCP remoto.
2. O cliente encaminha-o para o início de sessão do invoiso. Inicie sessão como habitualmente.
3. Aprove o acesso descrito pelo ecrã de consentimento. Ele indica o espaço que está a ligar.
4. Está ligado. Pergunte ao seu cliente algo sobre as suas contas — «quanto faturei no mês passado?» é uma boa primeira pergunta, porque não precisa de permissões além da leitura.

Os âmbitos pedidos são openid, email, profile e user:org:read. O último é o que nos diz que espaço está a ligar; sem ele o servidor recusa em vez de adivinhar — ver abaixo.

A que espaço está ligado

Está ligado ao espaço que estava ativo no seu navegador quando aprovou a ligação. O ecrã de consentimento indica-o. É a mesma regra que o navegador segue — uma sessão está num espaço de cada vez — e significa que mudar de espaço no invoiso não muda o que o seu cliente MCP vê.

Para apontar um cliente a outro espaço: mude primeiro para esse espaço no invoiso, depois remova e volte a adicionar a ligação no seu cliente. Passará de novo pelo consentimento, e o novo token leva o novo espaço.

Se o servidor não conseguir determinar a que espaço pertence um token, responde 403 com error="insufficient_scope", indicando o âmbito a pedir, em vez de escolher um. Escolher seria pior do que recusar: a resposta errada plausível é o seu espaço pessoal vazio, e concluiria que o invoiso perdeu as suas contas.

O que o seu plano pode fazer

Tudo está disponível para o assistente dentro do invoiso em qualquer plano. O que muda num cliente MCP externo é se pode escrever.

Uma ligação apenas de leitura não é um cliente reduzido — são todas as ferramentas que apenas relatam. A escrita a partir de um cliente externo começa no Business. Peça a uma ligação apenas de leitura para alterar algo e ela di-lo numa frase sem mudar nada, em vez de falhar de forma obscura.

O que as ferramentas fazem

Há 167 ferramentas. 63 delas apenas relatam; as restantes escrevem. Cada ferramenta traz as três anotações que o MCP define — readOnlyHint, destructiveHint e openWorldHint — para que o seu cliente lhe possa perguntar antes de fazer algo irreversível. 15 delas podem alterar algo fora do invoiso: enviar um e-mail, publicar uma página de pagamento, escrever no Xero ou no QuickBooks. São essas que vale a pena o cliente confirmar.

Os valores são sempre indicados duas vezes

Um espaço pode conter documentos em várias moedas. Qualquer ferramenta que devolva um valor devolve-o na moeda do próprio documento e na moeda de relato do espaço, convertida à taxa fixada nesse documento. Só a segunda é comparável entre documentos, e as instruções do servidor dizem ao modelo para nunca somar dois valores em moedas diferentes. Onde nenhuma taxa cobria uma data, o valor de relato é null em vez de zero.

Os totais vêm da ferramenta de relatórios

run_report responde às perguntas «quanto». As ferramentas de listagem listam; somar uma lista não é a mesma aritmética — os rascunhos e as notas de crédito contam de outra forma — e a descrição de cada ferramenta diz qual é.

O que o servidor lê e o que guarda

Uma chamada de ferramenta lê e escreve os dados do seu espaço: as suas faturas, despesas, contactos, produtos e definições. As respostas trazem os registos pedidos — para um contacto, o nome, e pode incluir um e-mail, uma morada ou um número de identificação fiscal, porque é isso que aparece numa fatura.

O servidor não guarda qualquer cópia separada de uma conversa, não envia nenhuma resposta de ferramenta para lado nenhum a não ser de volta ao cliente que perguntou, e nunca devolve credenciais, chaves de API ou tokens OAuth — seus ou de um serviço ligado. O que fazemos com os dados em geral, incluindo que terceiros recebem o quê, está na política de privacidade, e os termos aplicam-se a esta ligação como a qualquer outra.

Desligar

Remova a ligação no seu cliente MCP. Isso basta: o token é a única coisa que concede acesso, e do nosso lado nada continua a funcionar sem ele. Apagar a sua conta invoiso remove tudo o que está por trás — a política de privacidade diz o que isso significa e quanto tempo demora.

Detalhes do protocolo

O servidor negoceia 2025-06-18, 2025-03-26 e 2024-11-05, respondendo com a mais recente que ele e o cliente compreendem ambos. A uma versão não reconhecida responde com a mais recente que suportamos, em vez de recusar, que é o que a especificação pede.

A autorização segue OAuth 2.1 com PKCE. A descoberta são os metadados de recurso protegido RFC 9728 em https://www.invoiso.com/.well-known/oauth-protected-resource, e o servidor de autorização publica documentos de descoberta RFC 8414 e OpenID Connect. Os clientes registam-se sozinhos por registo dinâmico (RFC 7591), razão pela qual os passos acima não lhe pedem mais do que um URL. O endpoint de registo é anunciado apenas no documento RFC 8414; um cliente que leia só o de OpenID Connect não o encontrará e precisará do id de cliente predefinido abaixo.

Se o seu cliente não conseguir registar-se sozinho e pedir um id de cliente, escreva para support@invoiso.com e damos-lhe um. Deixe o segredo do cliente vazio — o cliente é público e autentica-se com PKCE.

Os tokens são verificados contra o JWKS da nossa própria instância e têm de trazer o nosso emissor e o âmbito que nomeia o seu espaço. Um token emitido por outra instalação do invoiso, ou por outra instância Clerk, é recusado. Um token de outra aplicação registada nesta esta instância não é distinguível do nosso e é aceite — é isso que significa registo aberto, e é por isso que vale a pena ler o ecrã de consentimento, que nomeia a aplicação que pede, antes de o aprovar.

Se algo estiver errado

Escreva para support@invoiso.com com o que o seu cliente pediu e o que veio de volta. Um 401 costuma significar que a ligação precisa de ser aprovada de novo; um 403 que nomeia um âmbito significa que o cliente não o pediu; e uma recusa que nomeia o seu plano é a barreira de apenas leitura acima, não uma falha.