MCP Server

What @frihet/mcp-server MCP server does

The @frihet/mcp-server MCP server gives MCP-compatible AI clients an interface to Frihet’s business-management system. Its documented scope includes invoicing, expenses, clients, products, quotes, fiscal operations, HR, payroll, onboarding, permissions, period closing, and webhook testing. The repository describes 157 canonical catalogue operations, five fiscal aliases, ten prompts, and 11 resources in the local profile.

Typical interactions include asking an assistant to create an invoice, inspect expenses, or manage customer and product records. The server supports workflows in which an agent prepares a draft, presents it for review, and waits before an action with external effects is taken. Catalogue membership alone does not guarantee that every operation is enabled for every Frihet workspace.

How it works

The package can run locally over standard MCP client configuration using Node.js 20 or newer. It connects to Frihet with FRIHET_API_KEY; the key is obtained from the Frihet application’s API-key settings. A hosted MCP endpoint is also available at https://mcp.frihet.io/mcp, with OAuth or API-key authentication and no local package installation.

For testing, setting FRIHET_DEMO=1 starts a local, zero-setup mode. Responses come from realistic example fixtures, including Spanish invoices, expenses, clients, products, and a bank account. Records use demo_-prefixed identifiers, writes are simulated, nothing is persisted, and no network request is made. Fiscal actions in this mode are simulations rather than submissions to a tax authority.

The server returns capability metadata for tools and onboarding instructions for connected agents. Its guidance tells agents to inspect business context and tax-rate resources before acting, create fiscal documents as drafts by default, and avoid assuming human authority for actions involving inboxes, webhooks, money, or tax systems.

Setup and configuration

Install the local server through npm with:

npx -y @frihet/mcp-server

Configure the command in an MCP client and provide FRIHET_API_KEY in the environment for access to real Frihet data. The README gives JSON configuration examples for Claude Desktop, Cursor, Windsurf, and Cline, and command-based setup for Claude Code and Codex CLI. The package is also distributed through Smithery and listed in the MCP Registry.

For a safe trial, use:

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

The hosted option avoids local installation and uses the published MCP URL. Authentication details depend on whether the client connects with OAuth or an API key.

Tools and capabilities

The @frihet/mcp-server MCP server covers business-management operations such as:

• Creating and querying invoices, quotes, and credit notes.
• Working with expenses, clients, products, and bank-account data.
• Supporting fiscal processes associated with e-invoicing, VeriFactu, TicketBAI, and FACe.
• Handling HR, payroll, onboarding, permissions, and period-close operations described in the catalogue.
• Exposing local resources, hosted static resources, prompts, aliases, and discovery names according to the selected profile.

Draft defaults and confirmation controls are relevant for workflows that can create records or cause external side effects. Agents should inspect the tool metadata and returned instructions rather than infer that an operation is available or safe for a particular workspace.

Limitations and notes

The local and hosted profiles do not expose identical surfaces. The local package serves 11 resources, while the hosted Worker serves seven static resources; API-backed workspace resources are local-profile only. The hosted grouped profile also includes three local discovery names. The README reports multiple catalogue and tool counts for these profiles, so the effective surface depends on how the server is connected.

Demo mode cannot be used for real submissions or persistent records. Production use requires access to Frihet and an API key for the local package. External-side-effect tools may reach a client inbox, webhook, financial workflow, or tax authority, so they require deliberate human approval where indicated.