Qual a diferença entre Recursos e Ferramentas no MCP?

As Ferramentas executam ações contra a API (criar fatura, listar despesas). Os Recursos expõem dados de referência estáticos que o agente pode consultar sem fazer chamadas à API. Tipos de impostos, calendários fiscais ou categorias de despesas estão sempre disponíveis como contexto.

O que são os Prompts MCP e como são usados?

Os Prompts são fluxos de trabalho guiados que encadeiam múltiplas ferramentas em uma sequência lógica. Em vez de executar operações soltas, um prompt como monthly-close guia o agente passo a passo: revisar faturas pendentes, categorizar despesas, verificar obrigações fiscais.

Preciso atualizar algo para usar a v1.2?

Se você usa npx @frihet/mcp-server, obtém a última versão automaticamente. Se você tem uma instalação fixa, atualize com npm update @frihet/mcp-server. Não há mudanças disruptivas em relação à v1.1.0.

Servidor MCP v1.2: recursos, prompts e output estruturado

A versão 1.2.1 do servidor MCP da Frihet não adiciona mais ferramentas. Adiciona inteligência. Recursos para que os agentes tenham contexto fiscal sem perguntar. Prompts para que executem fluxos completos sem intervenção. Output estruturado para que cada resposta seja parseável de forma determinística.

Esta atualização transforma o servidor MCP de uma ponte de operações CRUD em uma interface de gestão empresarial completa para agentes de IA.

Recursos: dados de referência sempre disponíveis

Os Recursos MCP são dados estáticos que o agente pode ler a qualquer momento sem fazer chamadas à API da Frihet. Não consomem cota, não exigem autenticação adicional e estão disponíveis a partir do momento em que o servidor se conecta.

A v1.2 introduz 5 recursos:

`frihet://api/schema`

Resumo de todos os endpoints disponíveis, métodos de autenticação e limites de taxa. Quando um agente precisa saber o que pode fazer com a Frihet, consulta este recurso em vez de descobri-lo por tentativa e erro.

`frihet://tax/rates`

Tipos de impostos vigentes na Espanha: IVA geral (21%), reduzido (10%) e superreduzido (4%); IGIC canário (7%, 3%, 0%); retenções IRPF. O agente tem este contexto antes de criar uma fatura ou registrar uma despesa. Não precisa perguntar qual IVA aplicar se já sabe onde seu negócio opera.

`frihet://tax/calendar`

Datas de apresentação de declarações trimestrais: Modelo 303 (IVA), Modelo 130 (IRPF), Modelo 420 (IGIC). Quando o agente prepara um fechamento trimestral, sabe exatamente quando vence cada obrigação.

`frihet://config/expense-categories`

As 8 categorias de despesas com suas regras de dedutibilidade. Material de escritório, suprimentos, transporte, diárias, treinamento, seguros, serviços profissionais, outros. Cada categoria inclui o percentual de dedutibilidade e as condições que se aplicam.

`frihet://config/invoice-statuses`

O fluxo de status de uma fatura: rascunho, emitida, enviada, cobrada, vencida, anulada. Cada status inclui as transições permitidas e os triggers que podem ser ativados (webhooks, notificações). O agente sabe quais ações são válidas a cada momento.

Prompts: fluxos de trabalho guiados

Uma Ferramenta executa uma operação. Um Prompt orquestra várias operações em um fluxo coerente. A diferença é passar de “crie esta despesa” para “processe estes 15 tickets de despesa, categorize-os, aplique os impostos corretos e confirme antes de criar”.

A v1.2 inclui 5 prompts:

`monthly-close`

Fechamento mensal guiado. O agente revisa faturas pendentes de cobrança, categoriza despesas não atribuídas, verifica se as obrigações fiscais do período estão cobertas e gera um resumo. Um fluxo que normalmente leva uma hora de revisão manual, executado em uma conversa.

`onboard-client`

Cadastro de novo cliente. Determina o tipo de imposto de acordo com a localização do cliente (IVA peninsular, IGIC canário, intracomunitário), cria o registro com os dados fiscais corretos e gera um orçamento de boas-vindas. Tudo em uma sequência.

`quarterly-tax-prep`

Preparação trimestral de impostos. Coleta todas as faturas do período, calcula as bases tributáveis de IVA ou IGIC, aplica as retenções de IRPF e gera uma pré-visualização do Modelo 303 ou 130. O agente faz o trabalho; você ou seu contador validam o resultado.

`overdue-followup`

Acompanhamento de faturas vencidas. Identifica todas as faturas fora do prazo, agrupa-as por cliente, calcula o valor total pendente por cada um e redige mensagens de cobrança personalizadas. De “preciso verificar o que me devem” para “aqui estão os rascunhos prontos para enviar”.

`expense-batch`

Processamento de despesas em lote. Recebe uma lista de despesas, categoriza-as de acordo com as regras configuradas, aplica os impostos correspondentes, verifica a dedutibilidade de cada uma e as cria com confirmação prévia. Ideal para processar tickets acumulados de uma semana ou uma viagem.

Output estruturado: respostas parseáveis

Até agora, as respostas do servidor MCP eram texto formatado. Útil para leitura humana, mas os agentes precisam de dados estruturados para tomar decisões programáticas.

A v1.2 adiciona outputSchema e structuredContent a cada ferramenta. Cada resposta inclui um esquema JSON que descreve exatamente a estrutura dos dados retornados. O agente sabe antes de chamar quais campos irá receber, de que tipo são e quais são opcionais.

Isso é o que permite que um prompt como quarterly-tax-prep encadeie 4 operações de forma confiável: cada passo produz dados com uma estrutura conhecida que o próximo passo pode consumir sem ambiguidade.

Para desenvolvedores que constroem integrações sobre o servidor MCP, isso elimina a necessidade de parsear texto livre. A resposta sempre tem a mesma forma.

Anotações de segurança

Cada ferramenta do servidor MCP agora inclui anotações que indicam se a operação é somente leitura ou destrutiva. Um list-invoices é marcado como leitura. Um delete-expense é marcado como destrutivo.

Isso permite que os agentes implementem políticas de confirmação. Um agente pode executar operações de leitura sem perguntar, mas solicitar confirmação explícita antes de excluir ou modificar dados. A segurança não depende do agente — ela é definida pelo servidor.

Instalação universal

O servidor é instalado com um único comando em qualquer agente compatível:

npx @frihet/mcp-server

Funciona no Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Codex e qualquer cliente MCP. Para agentes que suportam instalação via skills:

npx skills add Frihet-io/frihet-mcp

Ambos métodos dão acesso às mais de 30 ferramentas, aos 5 recursos, aos 5 prompts e ao output estruturado.

Repositório sob Frihet-io

O servidor MCP foi transferido para a organização Frihet-io no GitHub. A URL do repositório é agora github.com/Frihet-io/frihet-mcp. Os links anteriores redirecionam automaticamente.

O pacote npm continua sendo @frihet/mcp-server. Não há mudanças na instalação.

Para quem é esta atualização

Profissionais que já usam o servidor MCP ganham Recursos como contexto fiscal automático e Prompts como fluxos que antes executavam passo a passo de forma manual.

Desenvolvedores que constroem sobre a Frihet ganham output estruturado para integrações determinísticas e anotações de segurança para políticas de confirmação.

Escritórios de contabilidade e consultores fiscais ganham prompts específicos para seus fluxos de trabalho: fechamento mensal, preparação trimestral, acompanhamento de cobranças.

Qualquer negócio que use agentes de IA ganha um servidor MCP que não apenas executa operações, mas sabe como encadeá-las em fluxos de negócio reais.

Como atualizar

Se você usa npx @frihet/mcp-server, já tem a última versão. Se você tem uma instalação fixa:

npm update @frihet/mcp-server

Não há mudanças disruptivas. Todas as ferramentas existentes mantêm sua interface. Os Recursos, Prompts e output estruturado são adições puras.

A documentação completa está em docs.frihet.io/desenvolvedores. O código-fonte no GitHub (Frihet-io/frihet-mcp). O pacote no npm como @frihet/mcp-server.