Frihet MCP Server

O primeiro servidor MCP nativo de IA para um ERP espanhol. Crie faturas, gerencie despesas, acompanhe clientes, lide com produtos, orçamentos e webhooks — tudo por meio de linguagem natural com qualquer assistente de IA. 31 ferramentas, bilíngue ES/EN.

GitHub

Documentação

Servidor MCP nativo com IA para gestão empresarial.
Servidor MCP nativo con IA para gestión empresarial.

_{Funciona com Claude · ChatGPT · Cursor · Windsurf · Cline · Antigravity · Codex · Copilot · Gemini CLI — e qualquer cliente compatível com MCP.}

Frihet MCP — talk to your ERP in natural language

Distribuição

Canal	Status	Instalação
npm	Ativo	`npx @frihet/mcp-server`
Endpoint remoto	Ativo	`https://mcp.frihet.io/mcp` (instalação zero, OAuth ou chave de API)
Smithery	Ativo	smithery.ai/servers/frihet/frihet-mcp
MCP Registry	Ativo	registry.modelcontextprotocol.io
GitHub MCP Registry	Ativo	github.com/mcp/io.frihet/erp
Glama	Ativo	glama.ai/mcp/servers/Frihet-io/frihet-mcp
mcp.so	Auto-indexado (não verificado)	mcp.so — indexa a partir do npm + GitHub
PulseMCP	Auto-indexado (não verificado)	pulsemcp.com — indexa a partir do npm + GitHub
Cursor Marketplace	Em breve	cursor.com/marketplace
ChatGPT Apps	Em breve	chatgpt.com
Anthropic Claude Directory	Em breve	claude.ai/settings/connectors

Fonte da verdade: o catálogo contém 156 operações canônicas. O perfil completo local oferece 161 nomes de ferramentas, 11 recursos e 10 prompts (156 operações canônicas mais 5 aliases fiscais). O perfil agrupado hospedado oferece 164 nomes de ferramentas, 7 recursos e 10 prompts (os mesmos nomes mais 3 ferramentas de descoberta, com recursos apoiados por API mantidos apenas localmente). O perfil OpenAI revisado separadamente oferece 33 nomes de ferramentas, 0 recursos e 0 prompts. A associação ao catálogo não é uma garantia de que uma API de suporte esteja habilitada para cada workspace.

O que é isto

Um servidor MCP que conecta seu assistente de IA ao Frihet. Crie faturas conversando. Consulte despesas em linguagem natural. Gerencie todo o seu negócio a partir da sua IDE.

You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/hour, due March 1st"
Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.

156 operações canônicas. Cinco aliases fiscais. Dez prompts. O pacote local oferece 11 recursos; o Worker hospedado deliberadamente oferece os 7 recursos estáticos, enquanto os recursos de workspace apoiados por API permanecem apenas no perfil local.

Experimente instantaneamente (sem cadastro)

Teste sem nenhuma configuração — sem conta, sem chave de API:

FRIHET_DEMO=1 npx -y @frihet/mcp-server

No modo demo, o servidor responde com exemplos de fixtures realistas (faturas espanholas com IVA/IGIC, despesas, clientes, produtos, uma conta bancária e mais) — cada registro usa IDs com prefixo demo_ e o servidor imprime um banner DEMO MODE na inicialização. Nada é persistido e nenhuma chamada de rede é feita. Gravações são simuladas e ações fiscais (e-invoice, VeriFactu, TicketBAI, FACe, folha de pagamento) retornam uma simulação claramente rotulada — nunca um envio real a qualquer autoridade tributária.

Quando estiver pronto para seus dados reais, remova a flag e adicione sua chave (app.frihet.io → Configurações → Chaves de API). Veja Instalação abaixo.

Para agentes de IA

Se você é um agente lendo este repositório em vez de uma pessoa lendo uma página, tudo o que você precisa é legível por máquina e gerado a partir do servidor em execução — você não precisa analisar este README.

O quê	Onde
Contrato de integração: guia rápido por cliente, autenticação, fluxo de trabalho seguro, listas de ferramentas com autoridade humana, recuperação de erros	`docs/agent-onboarding.json` — também incluído no pacote npm
Verdade de capacidade por ferramenta: `callability`, `writesFrihet`, `externalInteraction`, `externalSideEffects`	`_meta["io.frihet/capability"]` em cada entrada de `tools/list`
Como se comportar após conectar	a string `instructions` retornada por `initialize` — seu cliente a entrega a você automaticamente

Três regras que o contrato codifica, em resumo:

Oriente-se antes de agir. get_business_context e o recurso frihet://tax/rates decidem o tratamento fiscal correto. Não recupere uma taxa de imposto espanhola da memória.
Rascunhe, mostre, pare. create_invoice, create_quote e create_credit_note todos usam como padrão status=draft — nenhum número fiscal, nenhum hash, nada enviado a uma autoridade tributária. Apresente o rascunho e devolva.
Autoridade humana não é sua para assumir. Qualquer ferramenta com um externalSideEffects não vazio alcança a caixa de entrada de um cliente, um webhook, dinheiro ou AEAT / VeriFactu / TicketBAI / FACe. Várias também aceitam confirm=true; essa flag registra uma decisão humana — nunca a defina para satisfazer seu próprio plano.

docs/agent-onboarding.json é regenerado a partir da superfície ativa por npm run generate:agent-onboarding e controlado no CI por npm run gate:agent-onboarding, portanto suas listas de ferramentas e contagens não podem divergir do servidor.

Instalação

Uma linha (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI e mais)

npx skills add Frihet-io/frihet-mcp

Plugin Claude Code (skill + servidor MCP em uma única instalação)

Este repositório também é um plugin Claude Code (frihet-erp): instalá-lo conecta tanto a skill de gestão empresarial quanto o servidor MCP.

# Try it locally
claude --plugin-dir /path/to/frihet-mcp

A disponibilidade no marketplace está pendente. Use o comando de plugin local acima ou o comando MCP do Claude Code abaixo para conectar hoje.

Invocação da skill: /frihet-erp:frihet-mcp. O .mcp.json incluído inicia @frihet/mcp-server via npx — defina FRIHET_API_KEY no seu ambiente (obtenha um em app.frihet.io → Configurações → Chaves de API).

A prévia do plugin Claude portátil inclui skills reais de contas a receber, elaboração de documentos e revisão mensal com o MCP remoto público existente. Carregue plugins/claude/frihet-erp no Claude Code ou envie um ZIP dessa pasta no chat/Cowork. Suas skills orientam o comportamento; elas não filtram o catálogo hospedado nem estabelecem aprovação do Directory. A configuração MCP local raiz acima mantém sua configuração de chave de API existente.

Claude Code — um comando

claude mcp add frihet -s user -e FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
claude mcp list          # verify: frihet ✓ Connected

A CLI é dona do arquivo de configuração, então não há nada para editar manualmente e nenhum caminho para errar. (O escopo do usuário grava ~/.claude.json, não ~/.claude/mcp.json.)

Codex CLI — um comando

codex mcp add frihet --env FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
codex mcp list           # verify

A configuração do Codex é TOML, não JSON. codex mcp add grava:

[mcp_servers.frihet]
command = "npx"
args = ["-y", "@frihet/mcp-server"]

[mcp_servers.frihet.env]
FRIHET_API_KEY = "fri_your_key_here"

Colar um bloco JSON mcpServers em ~/.codex/config.toml é um erro de análise TOML que derruba toda a sua configuração do Codex, não apenas este servidor. Use o comando acima.

Claude Desktop, Cursor, Windsurf, Cline — configuração JSON

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

Ferramenta	Arquivo de configuração
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Cursor	`.cursor/mcp.json` ou `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	Configurações do VS Code ou `.cline/mcp.json`

O JSON acima é idêntico para esses quatro clientes; apenas o caminho do arquivo muda. Claude Code e Codex não estão nesta tabela — eles gerenciam sua própria configuração por meio dos comandos CLI mostrados acima.

Remoto (sem instalação)

Use o endpoint hospedado em mcp.frihet.io — zero dependências locais, executa em Cloudflare Workers.

Com chave de API:

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

Com OAuth 2.0 + PKCE (login baseado em navegador, sem necessidade de chave de API):

Clientes que suportam OAuth (Claude Desktop, Smithery, etc.) podem conectar diretamente a https://mcp.frihet.io/mcp e autenticar via navegador. O servidor implementa o fluxo completo de código de autorização OAuth 2.1 com PKCE.

Obtenha sua chave de API

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

O que você pode fazer

Fale com seu ERP. Estes são prompts reais, não texto de marketing.

Faturamento

"Show me all unpaid invoices"
"Create an invoice for Acme SL with 10h of consulting at 95/hour"
"Mark invoice abc123 as paid"
"How much has ClientName been invoiced this year?"

Despesas

"Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible"
"List all expenses from January"
"What did I spend on travel last quarter?"

Clientes

"Add a new client: TechStart SL, NIF B12345678, email admin@techstart.es"
"Show me all my clients"
"Update ClientName's address to Calle Mayor 1, Madrid 28001"

CRM

"Add a contact to Acme SL: Ana Garcia, CTO, ana@acme.es"
"Log a call with TechStart: discussed Q2 proposal, they're interested in upgrade"
"Add a note to ClientName: prefers invoices in English, payment NET 30"
"Show me all activities for Acme SL"

Orçamentos

"Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)"
"Show me all pending quotes"

Webhooks

"Set up a webhook to notify https://my-app.com/hook when invoices are paid"
"List all my active webhooks"

O que esperar

Este MCP é uma interface de dados estruturados — você descreve o que deseja em linguagem natural, e a IA cria, consulta ou modifica registros de negócios no Frihet. A maioria das 156 operações canônicas são operações CRUD sobre a API REST; o restante são resumos somente leitura e ações fiscais/e-invoice. Nomes de aliases e descoberta são contados separadamente.

Funciona muito bem:

"Create an invoice for TechStart SL, 40h consulting at 75 EUR/h"   --> creates the invoice
"Show unpaid invoices over 1,000 EUR"                               --> queries and filters
"Log a 120 EUR expense for the Madrid train, category: travel"      --> records the expense
"Update client Acme's email to billing@acme.es"                     --> modifies the record

Não faz:

OCR ou digitalização de PDF — você não pode enviar uma imagem de fatura e tê-la lida
Upload de arquivos ou manipulação de anexos
Processamento de imagens de qualquer tipo

Se você precisar digitalizar faturas ou recibos em papel, extraia os dados primeiro (por exemplo, Claude Vision API, um serviço OCR dedicado ou entrada manual) e depois use o MCP para criar o registro:

1. Scan/photograph the invoice
2. Use Claude Vision: "Read this invoice image and extract the vendor, items, amounts, and dates"
3. Then: "Create an expense in Frihet for [extracted data]"

Operações do catálogo (156)

Faturas (12)

Ferramenta	O que faz
`list_invoices`	Lista faturas com paginação
`get_invoice`	Obtém detalhes completos da fatura por ID
`create_invoice`	Cria uma nova fatura com itens de linha
`update_invoice`	Atualiza qualquer campo da fatura
`delete_invoice`	Exclui uma fatura em rascunho; uma enviada/paga é cancelada, não destruída (`confirm=true` obrigatório)
`search_invoices`	Encontra faturas por nome do cliente, data ou status
`send_invoice`	Envia fatura por e-mail ao cliente (anexo PDF) — alcança terceiros, `confirm=true` obrigatório
`mark_invoice_paid`	Marca uma fatura como paga com data de pagamento opcional
`get_invoice_pdf`	Obtém bytes do PDF da fatura limitados como base64
`get_invoice_einvoice`	Obtém bytes XML ou PDF Factur-X limitados para uma fatura
`create_credit_note`	Cria uma nota de crédito vinculada a uma fatura existente
`apply_late_fee`	Aplica uma taxa de atraso a uma fatura vencida

Despesas (5)

Ferramenta	O que faz
`list_expenses`	Lista despesas com paginação
`get_expense`	Obtém detalhes da despesa
`create_expense`	Registra uma nova despesa
`update_expense`	Modifica uma despesa
`delete_expense`	Exclui uma despesa

Clientes (5)

Ferramenta	O que faz
`list_clients`	Lista todos os clientes
`get_client`	Obtém detalhes do cliente
`create_client`	Registra um novo cliente
`update_client`	Atualiza informações do cliente
`delete_client`	Remove um cliente

CRM: Contatos (3)

Ferramenta	O que faz
`list_client_contacts`	Lista todos os contatos de um cliente
`create_client_contact`	Adiciona uma pessoa de contato a um cliente
`delete_client_contact`	Remove um contato de um cliente

CRM: Atividades (2)

Ferramenta	O que faz
`list_client_activities`	Lista atividades de CRM (chamadas, e-mails, reuniões, tarefas)
`log_client_activity`	Registra uma chamada, e-mail, reunião ou tarefa contra um cliente

CRM: Notas (3)

Ferramenta	O que faz
`list_client_notes`	Lista todas as notas de um cliente
`create_client_note`	Adiciona uma nota de formato livre a um cliente
`delete_client_note`	Remove uma nota de um cliente

Produtos (5)

Ferramenta	O que faz
`list_products`	Listar produtos e serviços
`get_product`	Obter detalhes do produto
`create_product`	Adicionar um produto ou serviço
`update_product`	Atualizar preço ou detalhes
`delete_product`	Remover um produto

Cotações (6)

Ferramenta	O que faz
`list_quotes`	Listar todas as cotações
`get_quote`	Obter detalhes da cotação
`create_quote`	Criar um rascunho de nova cotação
`update_quote`	Modificar uma cotação
`delete_quote`	Excluir apenas um rascunho limpo, sem entrega, resposta, anexo ou evidência de conversão; recusar rascunhos protegidos; cancelar não-rascunhos (`confirm=true` obrigatório)
`send_quote`	Enviar cotação por e-mail ao cliente para aceitação

Webhooks (6)

Ferramenta	O que faz
`list_webhooks`	Listar webhooks configurados
`get_webhook`	Obter detalhes do webhook
`create_webhook`	Registrar um novo endpoint de webhook
`update_webhook`	Modificar eventos ou URL
`delete_webhook`	Remover um webhook
`test_webhook`	Enviar um payload de teste para um endpoint de webhook configurado

Inteligência (4)

Ferramenta	O que faz
`get_business_context`	Snapshot completo: perfil, plano, atividade recente, principais clientes, mês atual
`get_monthly_summary`	P&L mensal: receita, despesas, lucro, obrigação tributária, principais clientes por receita
`get_quarterly_taxes`	Preparação tributária trimestral: campos do Modelo 303/130, coletado vs. dedutível, obrigação
`duplicate_invoice`	Clonar uma fatura para cobrança recorrente (copia itens/cliente/imposto, inicia como rascunho)

Faturamento Eletrônico (10)

Ferramenta	O que faz
`send_einvoice`	Enviar uma fatura em 11 formatos (XRechnung, Factur-X, FatturaPA, PEPPOL, Facturae, UBL, CII) via e-mail / Chorus Pro / SDI / PEPPOL / download
`get_einvoice_status`	Consultar o status de execução do fluxo de trabalho Hatchet até sucesso/falha — retorna ackId, URL do XML, URL do PDF/A-3
`validate_einvoice_xml`	Validar XML bruto contra o esquema do formato + regras schematron (KOSIT / Mustang / XSD / Schematron)
`export_datev`	Exportar dados contábeis como DATEV EXTF (Buchungsstapel / Debitoren / Kreditoren) na codificação CP1252
`einvoice_export`	Exportar dados de fatura eletrônica em formatos legíveis por máquina (JSON/XML) para arquivamento ou integração
`face_submit`	Enviar fatura para FACe (plataforma espanhola de faturamento eletrônico B2G do governo)
`face_status`	Consultar o status de envio na FACe para uma fatura enviada
`ticketbai_submit`	Enviar registro fiscal TicketBAI para a autoridade tributária do País Basco (Hacienda)
`ticketbai_status`	Consultar o status de envio do TicketBAI na autoridade tributária basca
`ksef_submit`	NOT_DEPLOYED — Enviar fatura para KSeF (Polônia) — stub: o transporte está pronto na infraestrutura do Frihet-ERP, mas ainda não exposto como endpoint ativo (produção condicionada ao certificado KSeF); retorna erro rotulado como "indisponível" até ativação

Controle de Horas (6)

Ferramenta	O que faz
`list_time_entries`	Listar lançamentos de horas com filtro por usuário, projeto, intervalo de datas, status de faturamento
`get_time_entry`	Obter detalhes completos de um único lançamento de horas por ID
`create_time_entry`	Registrar horas para um projeto (marcador de faturamento, descrição, data)
`update_time_entry`	Atualizar qualquer campo em um lançamento de horas existente (semântica PATCH)
`delete_time_entry`	Exclusão lógica de um lançamento de horas (confirm=true obrigatório)
`get_time_summary`	Agregar total de horas faturáveis/não faturáveis para um período, com groupBy opcional (usuário/projeto/dia)

Faturas Recorrentes (8)

Ferramenta	O que faz
`list_recurring_invoices`	Listar todos os modelos de fatura recorrente (filtrar por ativo/pausado)
`get_recurring_invoice`	Obter detalhes completos de um modelo recorrente por ID
`create_recurring_invoice`	Criar um novo modelo de fatura recorrente (diário/semanal/mensal/trimestral/anual)
`update_recurring_invoice`	Atualizar campos do modelo — afeta apenas futuras faturas geradas
`pause_recurring_invoice`	Pausar um modelo ativo — nenhuma fatura é gerada enquanto pausado
`resume_recurring_invoice`	Retomar um modelo pausado — próxima fatura no próximo ciclo agendado
`delete_recurring_invoice`	Excluir permanentemente um modelo (confirm=true obrigatório)
`run_recurring_now`	Gerar a próxima fatura recorrente com `confirm=true` explícito nos modos completo e agrupado; as configurações do workspace podem acionar emissão fiscal, envio e webhooks

Gestão de Equipe (4)

Ferramenta	O que faz
`list_team_members`	Listar membros ativos + convites pendentes (proprietário excluído)
`invite_team_member`	Convidar um novo membro por e-mail com função (admin/editor/contador/visualizador)
`update_team_member_role`	Alterar a função de um membro existente (admin/editor/contador/visualizador)
`remove_team_member`	Remover um membro do workspace (confirm=true obrigatório)

Gestoria — Contadores (5)

Ferramenta	O que faz
`gestoria_message_send`	Enviar uma mensagem em um thread contextual (documentRequest / filingItem / obligation)
`gestoria_messages_list`	Listar mensagens em um thread, mais recentes primeiro; paginar para trás com `before`
`gestoria_template_create`	Criar um modelo reutilizável de solicitação de documento com variáveis + prazo em dias
`gestoria_template_bulk_send`	Envio em massa de um modelo para até 500 workspaces de clientes em uma única chamada
`gestoria_aging_consolidated`	Relatório de aging de contas a receber entre clientes (faixas, detalhamento por workspace, maiores atrasos)

Auditoria GL (3)

Ferramenta	O que faz
`frihet_gl_entry_approve`	Aprovar um lançamento contábil GL (somente gestor/admin — ÁREA DE CONFIANÇA)
`frihet_gl_entry_reject`	Rejeitar um lançamento GL com motivo obrigatório (ÁREA DE CONFIANÇA)
`frihet_gl_entry_audit_log`	Recuperar trilha de auditoria completa para um lançamento GL

Domínio do Portal White-label (3)

Ferramenta	O que faz
`frihet_portal_domain_add`	Adicionar um domínio personalizado ao portal do cliente (retorna registros DNS CNAME)
`frihet_portal_domain_verify`	Verificar propagação de DNS para um domínio de portal personalizado
`frihet_portal_domain_remove`	Remover um domínio de portal personalizado (reverte para o subdomínio padrão Frihet)

Auto-onboarding e VIES (2)

Ferramenta	O que faz
`frihet_portal_onboard_link_generate`	Gerar um link de auto-onboarding com validade para um cliente potencial
`frihet_tax_id_vies_lookup`	Validar um número de IVA da UE (CIF intracomunitário) via VIES

IGIC — Imposto Indireto das Canárias (4)

Ferramenta	O que faz
`frihet_modelo_415_summary`	M415 operações anuais >€3.005 (equivalente canário do M347) — não implantado, retorna `NOT_DEPLOYED`
`frihet_modelo_425_summary`	M425 resumo anual de IGIC para empresas das Ilhas Canárias — não implantado, retorna `NOT_DEPLOYED`
`frihet_modelo_418_summary`	M418 declaração mensal individual de IGIC, regime especial do grupo de entidades — não implantado, retorna `NOT_DEPLOYED`
`frihet_aiem_calculate`	Cálculo de AIEM (Arbitrio Importación) para Canárias — não implantado, retorna `NOT_DEPLOYED`

Imposto sobre Sociedades (2)

Ferramenta	O que faz
`frihet_modelo_200_summary`	Modelo 200 declaração anual de IS — não implantado, retorna `NOT_DEPLOYED`
`frihet_modelo_202_summary`	Modelo 202 pagamentos antecipados (1P/2P/3P) — não implantado, retorna `NOT_DEPLOYED`

Regras de Categorização Bancária (2)

Ferramenta	O que faz
`frihet_bank_rules_list`	Listar todas as regras de categorização automática bancária (condições + ações + status)
`frihet_bank_rule_create`	Criar uma nova regra para categorizar automaticamente transações por descrição, valor, contraparte

Depósitos (7)

Ferramenta	O que faz
`list_deposits`	Listar depósitos com paginação
`get_deposit`	Obter detalhes do depósito por ID
`create_deposit`	Registrar um novo depósito de cliente
`update_deposit`	Atualizar campos do depósito
`delete_deposit`	Excluir um depósito (confirm=true obrigatório)
`apply_deposit`	Aplicar um saldo de depósito contra uma fatura
`refund_deposit`	Registrar um reembolso de depósito na contabilidade Frihet com `confirm=true`; `amount` opcional registra essa parcela, a omissão registra o saldo reembolsável restante. Não transfere dinheiro

Fornecedores (5)

Ferramenta	O que faz
`list_vendors`	Listar todos os fornecedores
`get_vendor`	Obter detalhes do fornecedor
`create_vendor`	Adicionar um novo fornecedor
`update_vendor`	Atualizar informações do fornecedor
`delete_vendor`	Remover um fornecedor

Banco (5)

Ferramenta	O que faz
`list_bank_accounts`	Listar contas bancárias conectadas
`get_bank_account`	Obter detalhes de uma conta bancária
`list_transactions`	Listar transações bancárias com filtros
`categorize_transaction`	Atribuir uma categoria e tipo de despesa/receita a uma transação
`match_transaction_to_invoice`	Vincular uma transação bancária a uma fatura existente

Fiscal — Modelos Tributários Espanhóis (7)

Ferramenta	O que faz
`get_modelo_303_summary`	Declaração trimestral de IVA (Modelo 303) — coletado vs. dedutível, valor líquido a pagar
`get_modelo_130_summary`	Pagamento trimestral de IRPF para autônomos (Modelo 130)
`get_modelo_390_summary`	Resumo anual de IVA (Modelo 390)
`get_modelo_180_summary`	Resumo anual de retenções para aluguéis (Modelo 180) — não implantado, retorna `NOT_DEPLOYED`
`get_modelo_347_summary`	Transações anuais com terceiros >€3.005 (Modelo 347)
`verifactu_status`	Obter status de envio VeriFactu para um registro fiscal
`verifactu_resubmit`	Reenviar um registro fiscal VeriFactu rejeitado
`ticketbai_status`	Consultar o status de envio do TicketBAI — referência cruzada de Faturamento Eletrônico (10); NÃO contado para os 7 desta seção

Aluguel de Temporada / Stay (5)

Ferramenta	O que faz
`list_reservations`	Listar reservas de aluguel com filtros
`get_reservation`	Obter detalhes da reserva
`create_reservation`	Criar uma nova reserva
`list_properties`	Listar todas as propriedades de aluguel
`sync_channel`	Acionar sincronização de canal OTA (Airbnb, Booking.com, etc.)

PDV — Ponto de Venda (4)

Ferramenta	O que faz
`list_terminals`	Listar terminais PDV registrados
`get_sale`	Obter detalhes de uma transação de venda no PDV
`list_sales`	Listar vendas no PDV com paginação
`refund_sale`	Emitir um reembolso para uma venda no PDV

Cozinha / Restaurante (6)

Ferramenta	O que faz
`list_kitchen_tickets`	Listar tickets de pedido da cozinha para o painel ao vivo, filtrados por status ou estação
`get_kitchen_ticket`	Obter um único ticket de cozinha por ID com todos os itens e seus status individuais
`update_kitchen_ticket`	Avançar o status de um ticket (na fila → preparando → pronto → servido) ou reatribuí-lo a outra estação
`list_kitchen_stations`	Listar todas as estações da cozinha com id, nome e status ativo
`list_menu_items`	Listar o catálogo do menu da cozinha com busca de texto livre e filtro ativo/inativo
`kitchen_flow_summary`	Detecção de estação lenta: agregar tickets abertos por estação e sinalizar o gargalo

RH — Recursos Humanos (9)

Ferramenta	O que faz
`leave_request_create`	Criar uma solicitação de afastamento (férias, licença médica, pessoal)
`leave_approve`	Aprovar uma solicitação de afastamento pendente
`leave_reject`	Rejeitar uma solicitação de afastamento com motivo
`leave_cancel`	Cancelar uma solicitação de afastamento aprovada ou pendente
`leave_list`	Listar solicitações de afastamento com filtros (usuário, status, intervalo de datas)
`attendance_clock_in`	Registrar entrada (clock-in) de um funcionário
`attendance_clock_out`	Registrar saída (clock-out) de um funcionário
`overtime_report`	Ler horas extras diárias/semanais, agregar minutos/horas e alertas de conformidade calculados sobre os registros selecionados de YYYY ou YYYY-MM
`anomaly_list`	Listar anomalias de frequência (pontos ausentes, horas extras excessivas)

Folha de Pagamento (2)

Ferramenta	O que faz
`payroll_export`	Lê dados de funcionários normalizados prontos para folha de pagamento; o valor de formato é um rótulo de destino ecoado, não um arquivo gerado
`payroll_checklist`	Lista funcionários pagáveis com prontidão de perfil de folha, campos ausentes e estado de revisão mensal

Onboarding — retirado via #124

As ferramentas onboarding_status e onboarding_persona_set foram retiradas porque a família /v1/onboarding/* do Frihet-ERP não existe nesta versão. Consulte issue #124 para a auditoria e o precedente (src/tools/igic.ts mostra o padrão de stub inline NOT_DEPLOYED usado para famílias cuja API de suporte ainda não foi lançada; o onboarding optou pela retirada completa, porque o catálogo não deve prometer demais ferramentas que não têm handler ativo).

Se uma versão futura do Frihet-ERP lançar a família, restaure src/tools/onboarding.ts, os schemas onboardingStatusOutput / onboardingPersonaResultOutput em src/tools/shared.ts, os métodos getOnboardingStatus / setOnboardingPersona em IFrihetClient e o registro em src/tools/register-all.ts (o teste Onboarding tools — withdrawn via #124 em src/__tests__/d4b-hr-payroll-onboarding-tools.test.ts é o portão que falhará e lembrará o próximo mantenedor do que existia aqui).

Permissões (2)

Ferramenta	O que faz
`permissions_matrix`	Obtém o snapshot documentado do modelo RBAC (não é uma garantia de autorização em tempo de execução)
`permissions_me`	Compara campos do modelo RBAC com escopos reais de chaves de API e negações de escopo conhecidas (não exaustivo)

Fechamento de Período (3)

Ferramenta	O que faz
`period_close_status`	Obtém o intervalo do ano fiscal YYYY atual ou selecionado, estado aberto/fechado e detalhes de fechamento anuláveis
`period_close`	Fecha um período contábil (somente gestor/admin — ÁREA DE CONFIANÇA)
`period_reopen`	Reabre um período fechado com motivo obrigatório (ÁREA DE CONFIANÇA)

Todas as operações canônicas (e seus aliases) retornam saída estruturada via outputSchema — JSON tipado, não texto bruto. As formas de resposta de listas seguem sua família de API; nem todo endpoint de lista é paginado.

Verdade de capacidade e efeitos colaterais

Nas superfícies MCP completas, cada entrada tools/list inclui _meta["io.frihet/capability"]:

registered significa que o nome e o handler existem nesta compilação do servidor;
callability é api_dependent (o handler chama a API; implantação, habilitação de workspace e autorização ainda decidem), runtime_checked (o handler distingue explicitamente um backend ausente de dados vazios), deferred, unavailable ou local — nunca uma alegação incondicional de "disponível";
writesFrihet, externalInteraction e externalSideEffects distinguem mudanças de estado e chamadas a entidades/provedores externos;
As anotações de ação MCP permanecem a fonte padrão para dicas de somente leitura, destrutivas, idempotentes e de mundo aberto.

O host ChatGPT/OpenAI é uma superfície revisada separadamente: exatamente 33 operações de negócio com descrições completas, 0 meta-ferramentas de descoberta, 0 prompts e 0 recursos. Suas 17 leituras e 16 escritas são deliberadamente estreitas, e todas as escritas exigem confirm=true literal. Dez escritas podem entregar eventos de negócio completos a endpoints ativos previamente configurados pelo proprietário do workspace; a administração de webhooks em si permanece excluída. Entrega direta de e-mail, o resumo mensal legado, PDFs brutos de faturas, transições de ciclo de vida de faturas, atualização de um orçamento existente, arquivamento regulado, exclusão de registros pais de clientes, exclusão de despesas com seus arquivos vinculados, exclusão de produtos e exclusão de fornecedores também são excluídos. Esta superfície não deve ser inferida do catálogo completo.

Recursos

Contexto que a IA pode ler para tomar decisões mais inteligentes.

O pacote local serve 11 recursos: 7 referências estáticas mais 4 recursos de workspace com suporte de API. O Worker hospedado serve os 7 recursos estáticos. O host revisado pela OpenAI serve 0 recursos.

Estáticos (dados de referência, sem chamadas de API):

Recurso	URI	O que fornece
Schema da API	`frihet://api/schema`	Resumo OpenAPI: endpoints, autenticação, limites de taxa, paginação, códigos de erro
Alíquotas de Impostos	`frihet://tax/rates`	Alíquotas por zona fiscal espanhola: IVA, IGIC, IPSI, reverse charge da UE, IRPF
Calendário Fiscal	`frihet://tax/calendar`	Prazos de declaração trimestrais e anuais para os modelos fiscais espanhóis listados
Categorias de Despesas	`frihet://config/expense-categories`	8 categorias com regras de dedutibilidade, tratamento de IVA, amortização
Status de Faturas	`frihet://config/invoice-statuses`	Fluxo de status (rascunho > enviada > paga/vencida > cancelada), regras de transição, eventos de webhook
Moedas	`frihet://config/currencies`	40 moedas suportadas com códigos ISO, símbolos, casas decimais, formatação de localidade
Países	`frihet://config/countries`	61 países suportados com zonas fiscais, alíquotas padrão, moedas, prefixos de fatura

Dinâmicos (dados ao vivo da sua conta):

Recurso	URI	O que fornece
Perfil do Negócio	`frihet://business-profile`	Suas informações de negócio, plano, padrões, atividade recente, principais clientes
Snapshot Mensal	`frihet://monthly-snapshot`	P&L do mês atual, receita, despesas, obrigação tributária
Faturas Vencidas	`frihet://overdue-invoices`	Todas as faturas após a data de vencimento (até 100)
Limites do Plano	`frihet://status/plan-limits`	Nível do plano ao vivo, contadores de uso, faturas/mês, limites de taxa da API

Prompts (10)

Fluxos de trabalho pré-construídos que a IA pode executar como operações guiadas em várias etapas.

Prompt	O que faz	Argumentos
`monthly-close`	Fechar o mês: revisar faturas não pagas, categorizar despesas, verificar obrigações fiscais, gerar resumo	`month?` (AAAA-MM)
`onboard-client`	Configurar um novo cliente com alíquotas corretas por localização, opcionalmente criar um orçamento de boas-vindas	`clientName`, `country?`, `region?`
`quarterly-tax-prep`	Preparar declaração fiscal trimestral: calcular IVA/IGIC, identificar dedutíveis, pré-visualizar Modelo 303/130/420	`quarter?`, `fiscalZone?`
`overdue-followup`	Encontrar faturas vencidas, redigir mensagens de acompanhamento, sugerir lembretes de pagamento	--
`new-client-invoice`	Criar um cliente + primeira fatura em um único fluxo com consulta de alíquota	`clientName`, `country?`
`expense-report`	Gerar relatório de despesas agrupado por categoria com totais dedutíveis	`month?` (AAAA-MM)
`year-end-close`	Fechamento anual completo: revisão trimestral, faturas pendentes, despesas não categorizadas, checklist de fim de ano	`year` (AAAA)
`cash-flow-forecast`	Projetar fluxo de caixa para os próximos meses: receita recorrente, despesas, contas a receber vencidas, prazos fiscais	`months?` (padrão: 3)
`invoice-aging-review`	Análise de envelhecimento de contas a receber: agrupar faturas não pagas por faixa (0-30/31-60/61-90/90+ dias), principais devedores, ações de cobrança	--
`expense-batch`	Processar despesas em lote: categorizar, aplicar alíquotas, sinalizar recibos ausentes	`fiscalZone?`

Como funciona

graph LR
    AI["Your AI assistant"]
    MCP["frihet-mcp"]
    API["api.frihet.io"]
    DB["Frihet ERP"]

    AI -- "create_invoice()" --> MCP
    MCP -- "POST /v1/invoices" --> API
    API --> DB
    DB -- "201 + invoice data" --> API
    API -- "structured JSON" --> MCP
    MCP -- "typed response + suggestions" --> AI

    style AI fill:#09090b,stroke:#4ade80,color:#fafafa
    style MCP fill:#09090b,stroke:#fafafa,color:#fafafa
    style API fill:#09090b,stroke:#3f3f46,color:#a1a1aa
    style DB fill:#09090b,stroke:#3f3f46,color:#a1a1aa

O servidor traduz chamadas de ferramentas em solicitações REST API. Ele lida com autenticação, limite de taxa (repetição automática com backoff em 429), paginação e mapeamento de erros.

Dois transportes:

stdio (local) -- npx @frihet/mcp-server com FRIHET_API_KEY
Streamable HTTP (remoto) -- https://mcp.frihet.io/mcp com token Bearer ou OAuth 2.0+PKCE

Variáveis de ambiente

Variável	Obrigatória	Padrão
`FRIHET_API_KEY`	Sim (stdio)	--
`FRIHET_API_URL`	Não	`https://api.frihet.io/v1`
`FRIHET_TOOL_MODE`	Não	`full`
`FRIHET_CLAUDE_MODE`	Não (candidato local não lançado)	`false`

O candidato Claude somente-fonte requer compilar este checkout e executar dist/index.js; não se afirma que os lançamentos npm existentes suportam o sinalizador. Consulte escopo do candidato, exclusões e verificações. Ele não pode ser combinado com FRIHET_OPENAI_MODE=true e não está habilitado no Worker implantado.

Exposição de ferramentas: profundidade servida sob demanda

O diferencial do Frihet é profundidade — cobertura fiscal completa ES/UE mais conformidade nativa (VeriFactu, TicketBAI, Facturae/FACe; infraestrutura KSeF Polônia pronta, ativação pendente), bancos, CRM, RH/folha de pagamento, stay/PMS e POS. Mas uma lista plana de todas as ferramentas, carregada no contexto de um agente antecipadamente, é o problema de rotação de contexto de 2026: ela sufoca a tarefa e degrada a seleção de ferramentas antes que qualquer trabalho comece.

FRIHET_TOOL_MODE permite que você escolha como essa profundidade é exposta.

Modo	Comportamento
`full` (padrão)	Ferramentas canônicas e aliases fiscais são expostos com descrições e schemas completos. Descritores públicos adicionam verdade conservadora de chamabilidade e efeitos colaterais; nomes de operação, schemas e handlers permanecem inalterados.
`grouped`	Divulgação progressiva. A descrição de cada ferramenta é reduzida a um `[group] summary — full schema via describe_tool('name')` de uma linha, e três ferramentas leves de descoberta são adicionadas. O agente carrega profundidade apenas para as ferramentas que realmente precisa.

No modo grouped, nomes de operação, schemas de entrada e handlers permanecem inalterados. Descritores também expõem a mesma verdade conservadora de capacidade e ação que o perfil completo. A descoberta flui por três meta-ferramentas:

list_tool_groups() — o mapa de domínio (faturamento, despesas, fiscal/conformidade, bancos, CRM, RH/folha, stay/PMS, POS, inteligência, produtos, plataforma) com uma descrição de uma linha e contagem de ferramentas para cada um.
search_tools(query) — busca de texto livre em nome, título, resumo e grupo da ferramenta; retorna ferramentas correspondentes com seu grupo, resumo, sinalizador somente leitura e campos de entrada. Filtro opcional group e limit.
describe_tool(name) — a descrição original completa e campos de entrada para uma ferramenta, sob demanda, antes de chamá-la.

// claude_desktop_config.json — opt in to grouped mode
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_...",
        "FRIHET_TOOL_MODE": "grouped"
      }
    }
  }
}

A exposição agrupada muda a densidade da descrição, não o comportamento da operação. O perfil revisado pela OpenAI com versão é composto separadamente e permanece gated de forma independente.

Limites da API

Limite	Valor
Solicitações por minuto	100 por chave de API
Resultados por página	100 máx (50 padrão)
Corpo da solicitação	1 MB máx
Payload de webhook	100 KB máx
Webhooks por conta	20 máx

O limite de taxa é tratado automaticamente com backoff exponencial.

Habilidade do Claude Code

Além das ferramentas MCP brutas, este repositório inclui uma habilidade do Claude Code que adiciona contexto de negócio: regras fiscais espanholas, receitas de fluxo de trabalho, relatórios financeiros e comandos em linguagem natural.

Instalar a habilidade

git clone https://github.com/Frihet-io/frihet-mcp.git
ln -s "$(pwd)/frihet-mcp/skills/frihet-mcp" ~/.claude/skills/frihet-mcp

Ou com o instalador universal:

npx skills add Frihet-io/frihet-mcp

A habilidade roteia solicitações para as ferramentas MCP do Frihet (faturas, orçamentos, despesas, clientes, revisão mensal) e informa ao agente quando pedir confirmação antes de escritas. Ela não adiciona subcomandos /frihet independentes e não inclui alíquotas de IVA ou regras de dedutibilidade: os valores fiscais vêm dos seus dados do Frihet, não da habilidade.

Documentação completa: docs.frihet.io/desarrolladores/skill-claude-code

Desenvolvimento

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

Execute localmente:

FRIHET_API_KEY=fri_xxx node dist/index.js

Teste com o MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Contribuindo

Contribuições são bem-vindas. Por favor, abra uma issue primeiro para discutir o que você gostaria de mudar.

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build   # must pass before submitting

Limitações atuais

Sem OCR ou upload de arquivos -- o MCP trabalha com dados estruturados, não imagens ou PDFs.
Empresa única -- uma chave de API mapeia para um workspace do Frihet.
Conta Frihet necessária -- você precisa de uma conta ativa em app.frihet.io e uma chave de API (começa com fri_).

Ecossistema

Pacote	O que é
`@frihet/mcp-server`	Este servidor MCP (156 operações canônicas + 5 nomes de alias; 11 recursos locais; 10 prompts)
`@frihet/sdk`	SDK TypeScript (`frihet.invoices.create()`)
`frihet`	CLI (`frihet invoices list --status overdue`)
`n8n-nodes-frihet`	Nó comunitário n8n para automação de fluxos de trabalho
API REST	OpenAPI 3.1 em `api.frihet.io/v1`
MCP Remoto	Endpoint hospedado no Cloudflare Workers (instalação zero)
Webhooks	Eventos em tempo real com HMAC-SHA256

Licença

MIT. Consulte LICENSE.

Desenvolvido por Frihet.