Servidor MCP

O servidor MCP do Frihet implementa o Model Context Protocol para que assistentes de IA possam interagir diretamente com o seu ERP. Criar faturas, registrar despesas, consultar clientes ou gerenciar orçamentos — tudo a partir do seu IDE ou terminal, em linguagem natural.

Tu:      "Crea una factura para TechStart SL, 40 horas de consultoria a 75 EUR/hora, vencimiento 1 marzo"
Claude:  Hecho. Factura INV-2026-089 creada. Total: 3.000,00 EUR + 21% IVA = 3.630,00 EUR.

O que esperar (e o que não)

O servidor MCP é uma ponte stateless entre o seu assistente de IA e a API REST do Frihet. Cada chamada de ferramenta é traduzida em uma requisição HTTP para a API.

O que ele FAZ:

CRUD completo sobre faturas, despesas, clientes, produtos, orçamentos e webhooks
Busca de faturas por nome de cliente
Acesso a dados de referência (tipos de impostos, calendário fiscal, categorias)
Fluxos de trabalho guiados (fechamento mensal, preparação fiscal, acompanhamento de inadimplentes)

O que ele NÃO faz:

OCR de documentos (isso é feito pelo assistente de IA dentro do aplicativo)
Geração de PDFs (use a API REST diretamente: GET /v1/invoices/:id/pdf)
Processamento de pagamentos (as cobranças são gerenciadas via Stripe Connect no aplicativo)

Requisitos

Conta Frihet com acesso à API (planos pagos)
Chave de API gerada a partir do painel

Obter a chave de API

Faça login em app.frihet.io
Vá para Configurações > Desenvolvedores > API Keys
Clique em Criar chave de API
Copie a chave (começa com fri_) — ela é mostrada apenas uma vez

Instalação

Universal (mais de 30 agentes)

A forma mais rápida de instalar o servidor MCP e a skill de negócio:

npx skills add Frihet-io/frihet-mcp

Funciona com Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, e mais de 30 agentes.

MCP Registry

O servidor está registrado como io.frihet/erp no MCP Registry oficial. Clientes MCP compatíveis com o registro podem descobri-lo e instalá-lo automaticamente pelo seu nome canônico.

npx direto

npx -y @frihet/mcp-server@latest

Você não precisa instalar nada globalmente. O npx baixa e executa a versão mais recente automaticamente.

Configuração manual

Existem dois modos de conexão: local (o servidor é executado na sua máquina via npx) e remoto (conexão direta a mcp.frihet.io, sem instalar nada).

Local (stdio)

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server@latest"],
      "env": {
        "FRIHET_API_KEY": "fri_tu_clave_aqui"
      }
    }
  }
}

Remoto (streamable-http)

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_tu_clave_aqui"
      }
    }
  }
}

Configuração por cliente

A estrutura JSON é idêntica em todos os clientes. Apenas a localização do arquivo de configuração muda.

Cliente	Arquivo de configuração
Claude Code	`~/.claude/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` ou `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	Configuração do VS Code ou `.cline/mcp.json`
Codex CLI	`~/.codex/config.toml` (seção MCP)

dica

Se você usa o Claude Code, pode adicionar o servidor com um único comando:

claude mcp add frihet -- npx -y @frihet/mcp-server@latest

Depois, configure a variável FRIHET_API_KEY no arquivo ~/.claude/mcp.json resultante.

Variáveis de ambiente

Variável	Requerida	Valor padrão
`FRIHET_API_KEY`	Sim	--
`FRIHET_API_URL`	Não	`https://api.frihet.io/v1`
`FRIHET_MCP_DEBUG`	Não	`0`

FRIHET_API_URL é útil se você aponta para um ambiente de staging ou uma instância personalizada. Deve ser https:// com um hostname sob frihet.io.
FRIHET_MCP_DEBUG=1 ativa logs de nível de depuração (útil para diagnosticar problemas).

Fluxo OAuth

O servidor MCP suporta autenticação OAuth além da chave de API manual. Quando um cliente MCP inicia o fluxo OAuth:

O usuário se autentica via Firebase Auth (e-mail, Google, GitHub ou Microsoft)
O cliente envia o token de sessão para POST /api/oauth/api-key
O servidor provisiona uma nova chave fri_xxx... rotulada "MCP OAuth" com expiração de 365 dias
A chave é usada automaticamente para as chamadas subsequentes

Isso permite que os usuários conectem o servidor MCP sem copiar chaves manualmente.

Ferramentas disponíveis (52)

O servidor expõe 52 ferramentas organizadas em 7 categorias. Cada ferramenta inclui saída estruturada (outputSchema + structuredContent) para que os assistentes possam analisar respostas de forma confiável, além de anotações de segurança e conteúdo. Bilíngue (EN/ES).

Faturas (6 ferramentas)

Ferramenta	Descrição	Parâmetros chave
`list_invoices`	Lista faturas com paginação	`limit`, `offset`
`get_invoice`	Obtém uma fatura por ID	`id`
`create_invoice`	Cria uma fatura com linhas de detalhe	`clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`
`update_invoice`	Atualiza campos de uma fatura (parcial)	`id`, e qualquer campo a modificar
`delete_invoice`	Exclui uma fatura permanentemente	`id`
`search_invoices`	Busca faturas por nome de cliente	`clientName`, `limit`, `offset`

Estados possíveis da fatura: draft (rascunho), sent (enviada), paid (paga), overdue (vencida), cancelled (cancelada)

Despesas (5 ferramentas)

Ferramenta	Descrição	Parâmetros chave
`list_expenses`	Lista despesas com paginação	`limit`, `offset`
`get_expense`	Obtém uma despesa por ID	`id`
`create_expense`	Registra uma nova despesa	`description`, `amount`, `category`, `date`, `vendor`, `taxDeductible`
`update_expense`	Modifica uma despesa existente (parcial)	`id`, e qualquer campo a modificar
`delete_expense`	Exclui uma despesa permanentemente	`id`

Clientes (5 ferramentas)

Ferramenta	Descrição	Parâmetros chave
`list_clients`	Lista todos os clientes	`limit`, `offset`
`get_client`	Obtém um cliente por ID	`id`
`create_client`	Registra um novo cliente	`name`, `email`, `phone`, `taxId`, `address` (street, city, state, postalCode, country)
`update_client`	Atualiza dados de um cliente (parcial)	`id`, e qualquer campo a modificar
`delete_client`	Exclui um cliente permanentemente	`id`

Produtos (5 ferramentas)

Ferramenta	Descrição	Parâmetros chave
`list_products`	Lista produtos e serviços	`limit`, `offset`
`get_product`	Obtém um produto por ID	`id`
`create_product`	Cria um produto ou serviço	`name`, `unitPrice`, `description`, `taxRate`
`update_product`	Modifica um produto existente (parcial)	`id`, e qualquer campo a modificar
`delete_product`	Exclui um produto permanentemente	`id`

Orçamentos (5 ferramentas)

Ferramenta	Descrição	Parâmetros chave
`list_quotes`	Lista orçamentos	`limit`, `offset`
`get_quote`	Obtém um orçamento por ID	`id`
`create_quote`	Cria um orçamento para um cliente	`clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status`
`update_quote`	Modifica um orçamento (parcial)	`id`, e qualquer campo a modificar
`delete_quote`	Exclui um orçamento permanentemente	`id`

Estados possíveis do orçamento: draft (rascunho), sent (enviado), accepted (aceito), rejected (rejeitado), expired (expirado)

Webhooks (5 ferramentas)

Ferramenta	Descrição	Parâmetros chave
`list_webhooks`	Lista webhooks configurados	`limit`, `offset`
`get_webhook`	Obtém a configuração de um webhook	`id`
`create_webhook`	Registra um endpoint de webhook	`url`, `events[]`, `active`, `secret`
`update_webhook`	Modifica um webhook existente	`id`, e qualquer campo a modificar
`delete_webhook`	Exclui um webhook permanentemente	`id`

Eventos de webhook disponíveis: invoice.created, invoice.updated, invoice.deleted, invoice.paid, expense.created, expense.updated, expense.deleted, client.created, client.updated, client.deleted, product.created, product.updated, product.deleted, quote.accepted. Consulte Webhooks para o formato do payload e verificação HMAC.

Recursos disponíveis (8)

Os recursos MCP são dados de referência que o assistente pode consultar sem fazer chamadas à API. Eles são estáticos e sempre acessíveis.

Recurso	URI	Descrição
Esquema da API	`frihet://api/schema`	Resumo de endpoints, autenticação, limites de taxa e códigos de erro
Tipos de impostos	`frihet://tax/rates`	IVA (21/10/4%), IGIC (7/3/0%), IPSI, intracomunitário, IRPF (15%/7%)
Calendário fiscal	`frihet://tax/calendar`	Datas de apresentação trimestral (Modelo 303, 130, 420, 390)
Categorias de despesa	`frihet://config/expense-categories`	8 categorias com regras de dedutibilidade e tratamento fiscal
Estados da fatura	`frihet://config/invoice-statuses`	Fluxo de estados (rascunho, enviada, paga, vencida, cancelada) com gatilhos
Fornecedores	`frihet://config/vendors`	Lista de fornecedores registrados com dados fiscais e de contato
Integrações ativas	`frihet://config/integrations`	Status das integrações conectadas (Stripe, Shopify, etc.)
Configuração de negócio	`frihet://config/business`	Dados fiscais da empresa, zona fiscal, moeda e preferências

Prompts disponíveis (7)

Os prompts são fluxos de trabalho guiados que o assistente executa passo a passo. São invocados por nome.

Prompt	Descrição	Parâmetros
`monthly-close`	Fechamento mensal: revisa faturas não pagas, categoriza despesas, verifica obrigações fiscais, gera resumo	`month` (opcional)
`onboard-client`	Cadastro de cliente: determina tipo de imposto de acordo com a localização, cria registro, gera orçamento de boas-vindas	`clientName`, `country`, `region`
`quarterly-tax-prep`	Preparação fiscal trimestral: coleta faturas, calcula IVA/IGIC, gera prévia do Modelo 303/130	`quarter`, `fiscalZone`
`overdue-followup`	Acompanhamento de inadimplentes: identifica faturas vencidas, agrupa por cliente, redige mensagens de cobrança	—
`expense-batch`	Processamento de despesas em lote: categoriza, aplica impostos, verifica dedutibilidade, cria com confirmação	`fiscalZone`
`vendor-analysis`	Análise de fornecedores: agrupa despesas por fornecedor, calcula totais, identifica tendências e oportunidades de economia	`period` (opcional)
`business-health`	Diagnóstico de saúde do negócio: KPIs chave, comparativo com mês anterior, alertas e recomendações acionáveis	`month` (opcional)

dica

Você pode invocar um prompt diretamente: "Execute o fechamento mensal de fevereiro" ou "Prepare os impostos do Q1".

Exemplos de uso

Estas são requisições reais em linguagem natural que o assistente traduz para chamadas de ferramentas MCP.

Criar uma fatura

"Crea una factura para Acme SL con 10 horas de consultoria a 95 EUR/hora, vencimiento 15 de marzo"

O assistente chama create_invoice com clientName: "Acme SL", uma linha de detalhe (10 x 95) e dueDate: "2026-03-15". Calcula o total automaticamente.

Registrar uma despesa

"Registra un gasto de 59.99 EUR en Adobe Creative Cloud, categoria software, deducible"

Chama create_expense com description, amount: 59.99, category: "software" e taxDeductible: true.

Buscar faturas de um cliente

"Busca todas las facturas de TechStart SL"

Chama search_invoices com clientName: "TechStart SL" e retorna as correspondências com seus totais e status.

Consultar inadimplentes

"Muestrame todas las facturas sin pagar"

Chama list_invoices e filtra por status: "sent" ou "overdue", mostrando as vencidas ordenadas por valor.

Cadastrar um cliente

"Nuevo cliente: Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"

Chama create_client com nome, NIF, e-mail e endereço.

Configurar automação

"Crea un webhook para notificar a https://mi-app.com/hook cuando se pague una factura"

Chama create_webhook com url e events: ["invoice.paid"].

Atualizar um produto

"Sube el precio de la hora de consultoria a 85 EUR"

Chama update_product com o id do produto e unitPrice: 85. Apenas o campo indicado é modificado.

Observabilidade

O servidor MCP v1.5.1 inclui logging estruturado e métricas de ferramentas.

Logging estruturado

Todos os logs são emitidos como JSON para stderr (o MCP usa stdout para mensagens do protocolo). Cada entrada inclui:

level: debug, info, warn, error
service: sempre frihet-mcp
timestamp: ISO 8601
tool: nome da ferramenta (quando aplicável)
operation: tipo de operação (tool_call, api_call, api_retry, startup, shutdown_metrics)
durationMs: tempo de execução em milissegundos
error: detalhes do erro (message, code, statusCode)

Ative os logs de depuração com FRIHET_MCP_DEBUG=1.

Métricas de ferramentas

O servidor registra em memória as chamadas a cada ferramenta: número de invocações, erros e duração média. Ao fechar o servidor (SIGINT/SIGTERM), um resumo é emitido:

{
  "level": "info",
  "message": "Shutdown after 3600s — 42 calls, 1 errors",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}

Rate-limit retry automático

Quando a API responde com 429, o servidor tenta novamente automaticamente com backoff exponencial (até 3 novas tentativas). As novas tentativas são registradas no log:

{
  "level": "warn",
  "message": "Rate limited, retrying GET /invoices (attempt 2, delay 2000ms)",
  "operation": "api_retry"
}

Você não precisa gerenciar o rate limiting manualmente — o servidor faz isso por você.

Transporte

O servidor MCP do Frihet suporta dois modos de transporte. Ambos expõem as mesmas 52 ferramentas, 11 recursos e 10 prompts.

Local (stdio)

O servidor é executado como um processo local na sua máquina. A comunicação entre o cliente MCP e o servidor usa entrada/saída padrão (stdin/stdout).

Requer: Node.js instalado (é baixado automaticamente via npx)
Vantagem: Menor latência, funciona sem conexão à internet (exceto para as chamadas à API)
Caso de uso: Desenvolvimento diário, uso intensivo, ambientes corporativos com restrições de rede

Remoto (streamable-http)

O servidor é executado em Cloudflare Workers. Seu cliente MCP se conecta diretamente a https://mcp.frihet.io/mcp via HTTP.

Requer: Apenas conexão à internet
Vantagem: Sem instalação local, sem dependências, funciona em qualquer dispositivo
Caso de uso: Configuração rápida, equipes que preferem não instalar pacotes, clientes que só suportam transporte HTTP

informação

Se o seu cliente MCP não suporta streamable-http (alguns clientes antigos só suportam stdio), use o modo local.

Tratamento de erros

Rate limiting

A API permite 100 requisições por minuto por chave. Se o limite for excedido, o servidor retorna um erro 429 com o tempo de espera em retryAfter.

O servidor MCP gerencia automaticamente o rate limiting com backoff exponencial: tenta novamente a requisição após esperar o tempo indicado, sem intervenção do usuário. Máximo de 3 novas tentativas.

Erros de autenticação

Código	Causa	Solução
`401`	Chave de API inválida, expirada ou não fornecida	Verifique se a chave na sua configuração começa com `fri_` e não expirou
`403`	A chave não tem permissões para este recurso	Gere uma nova chave com as permissões necessárias

Outros erros

Código	Descrição
`400`	Parâmetros incorretos ou campos obrigatórios ausentes
`404`	O recurso solicitado não existe
`408`	Timeout da requisição (30 segundos)
`413`	O corpo da requisição excede 1 MB
`422`	Dados válidos, mas não processáveis (ex: perfil fiscal não configurado)
`429`	Limite de requisições excedido (é tentado novamente automaticamente)
`500`	Erro interno do servidor

Todos os erros retornam uma mensagem descritiva bilíngue (EN/ES) para que o assistente possa comunicar o problema ao usuário de forma clara.

Limites

Conceito	Valor
Requisições por minuto	100 por chave de API
Resultados por página	100 máximo (50 por padrão)
Corpo da requisição	1 MB máximo
Payload do webhook	100 KB máximo
Webhooks por conta	20 máximo
Timeout da requisição	30 segundos
Novas tentativas por rate limit	3 máximo

Diferença com a API REST

	Servidor MCP	API REST
Direcionado a	Assistentes de IA (Claude, Cursor, Windsurf)	Aplicativos, scripts, integrações
Comunicação	Linguagem natural através do cliente MCP	HTTP/JSON direto
Autenticação	Variável de ambiente na config do cliente (ou OAuth)	Cabeçalho `X-API-Key` ou `Authorization: Bearer`
Formato	Texto formatado + saída estruturada para o assistente	JSON bruto
Rate limiting	Gerenciado automaticamente (backoff exponencial, 3 novas tentativas)	Manual (o consumidor deve implementar novas tentativas)
Observabilidade	Logging estruturado + métricas por ferramenta	Logs de requisição via `X-Request-Id`
Caso de uso	Falar com seu ERP a partir do IDE	Construir integrações programáticas

Internamente, o servidor MCP traduz cada chamada de ferramenta em uma requisição à API REST. Não duplica lógica — é uma ponte stateless.

Desenvolvimento

Para contribuir ou executar o servidor em modo de desenvolvimento:

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Executar localmente:

FRIHET_API_KEY=fri_tu_clave node dist/index.js

Executar com logs de depuração:

FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_tu_clave node dist/index.js

Testar com o MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Recursos relacionados

API REST — Referência completa de endpoints, autenticação e códigos de erro
Webhooks — Eventos disponíveis, verificação HMAC-SHA256 e política de novas tentativas
Skill para Claude Code — Camada de inteligência de negócio sobre o servidor MCP
Código-fonte (GitHub) — Repositório do servidor MCP
Pacote npm — @frihet/mcp-server@1.5.1
MCP Registry — io.frihet/erp
Endpoint remoto — Servidor MCP hospedado em Cloudflare Workers
Especificação MCP — Documentação do protocolo

Anterior: Webhooks | Próximo: Skill para Claude Code

O que esperar (e o que não)​

Requisitos​

Obter a chave de API​

Instalação​

Universal (mais de 30 agentes)​

MCP Registry​

npx direto​

Configuração manual​

Local (stdio)​

Remoto (streamable-http)​

Configuração por cliente​

Variáveis de ambiente​

Fluxo OAuth​

Ferramentas disponíveis (52)​

Faturas (6 ferramentas)​

Despesas (5 ferramentas)​

Clientes (5 ferramentas)​

Produtos (5 ferramentas)​

Orçamentos (5 ferramentas)​

Webhooks (5 ferramentas)​

Recursos disponíveis (8)​

Prompts disponíveis (7)​

Exemplos de uso​

Criar uma fatura​

Registrar uma despesa​

Buscar faturas de um cliente​

Consultar inadimplentes​

Cadastrar um cliente​

Configurar automação​

Atualizar um produto​

Observabilidade​

Logging estruturado​

Métricas de ferramentas​

Rate-limit retry automático​

Transporte​

Local (stdio)​

Remoto (streamable-http)​

Tratamento de erros​

Rate limiting​

Erros de autenticação​

Outros erros​

Limites​

Diferença com a API REST​

Desenvolvimento​

Recursos relacionados​

O que esperar (e o que não)

Requisitos

Obter a chave de API

Instalação

Universal (mais de 30 agentes)

MCP Registry

npx direto

Configuração manual

Local (stdio)

Remoto (streamable-http)

Configuração por cliente

Variáveis de ambiente

Fluxo OAuth

Ferramentas disponíveis (52)

Faturas (6 ferramentas)

Despesas (5 ferramentas)

Clientes (5 ferramentas)

Produtos (5 ferramentas)

Orçamentos (5 ferramentas)

Webhooks (5 ferramentas)

Recursos disponíveis (8)

Prompts disponíveis (7)

Exemplos de uso

Criar uma fatura

Registrar uma despesa

Buscar faturas de um cliente

Consultar inadimplentes

Cadastrar um cliente

Configurar automação

Atualizar um produto

Observabilidade

Logging estruturado

Métricas de ferramentas

Rate-limit retry automático

Transporte

Local (stdio)

Remoto (streamable-http)

Tratamento de erros

Rate limiting

Erros de autenticação

Outros erros

Limites

Diferença com a API REST

Desenvolvimento

Recursos relacionados