Skip to main content

Connect Frihet to Claude, Cursor or ChatGPT

The job: let your AI assistant read and write in your ERP. Once connected, you talk to it in plain language and it runs the actions for you.

This works through the Frihet MCP server: 157 tools your agent uses as its own, compatible with 30+ AI clients.

Prerequisites, transport, and MCP profiles​

Before connecting your AI client, check which connection method and catalog profile (@frihet/mcp-server 1.17.0) match your environment:

DecisionLocal option (stdio)Remote option (streamable-http)
How it connectsRuns npx -y @frihet/mcp-server@1.17.0 on your machineConnects over HTTPS to https://mcp.frihet.io/mcp (zero local packages installed)
AuthenticationFRIHET_API_KEY=fri_... environment variable created in Integrations → API Keys (full access to /v1/* resources in your account)Authorization: Bearer fri_... header or browser OAuth 2.1 with PKCE sign-in
Local profile (localFull)162 tools registered (157 canonical business tools + 5 fiscal aliases such as frihet_modelo_303_summary)Not used on remote connections
Remote profile (remoteGrouped)Not used on local stdio processes165 tools registered (the 157 canonical operations + 5 fiscal aliases + 3 discovery meta-tools list_tool_groups, search_tools, and describe_tool to preserve context window)
Registered vs. callable toolsOut of the 165 catalog entries in /mcp.json (162 in localFull), 156 are directly callable (54 runtime_checked + 99 api_dependent + 3 discovery meta-tools; e.g., list_clients, list_invoices, create_invoice — callability: callable), 8 depend on specific workspace modules (period_close, create_reservation — callability: deferred), and 1 is disabled in production (ksef_submit — callability: unavailable)Beyond technical registration, every call enforces your account plan (e.g., create_webhook requires the Premium plan), your role permissions in Settings → Team, and your Settings → Tax Profile

1. Get your API key​

  1. Sign in to app.frihet.io
  2. Go to Integrations and open the API Keys tab
  3. Click Create API Key, name it and copy it (starts with fri_)

2. Connect your agent​

Quick option (30+ agents)​

npx skills add Frihet-io/frihet-mcp

Works with Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI and many more.

Manual configuration​

Add this to your client's MCP config (Claude Desktop, Cursor, Windsurf...) and set your key:

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

Client only supports HTTP? Use the remote endpoint https://mcp.frihet.io/mcp with Authorization: Bearer fri_.... The exact paths per client are in the MCP server guide.

Hermes Agent​

If you use Hermes Agent, install the Frihet plugin from its catalog with hermes plugins install frihet. The full steps are in Hermes Agent with Frihet.

3. Test it​

Talk to your agent:

"List my last 5 invoices"

If it answers with your real data, you're in. From here, any management task happens by talking.

Verify your first read and draft-first safety​

When you ask "List my last 5 invoices" or "Show my first 5 clients", the agent invokes a read-only operation (list_invoices or list_clients with limit: 5, equivalent to GET /v1/clients?limit=5 in Developers: getting started):

  • If your account already has records (for example, the synthetic test fixture Estudio Norte S.L.): the agent returns the structured list with legal name (Estudio Norte S.L.), tax ID (B12345674), email (facturacion@example.com), or invoice F-2026-0001 (1,815.00 EUR, status paid).
  • If your account is new and still empty: the MCP server responds 200 OK with data: [] and total: 0. That empty response still confirms that your fri_... key, MCP transport, and read permissions work properly.
  • Draft-first safety before writes: before asking for actions that create accounting documents or submit tax records (create_invoice, send_einvoice, create_credit_note), ask your agent to prepare a draft first or display the summary of client, tax ID, subtotal, and VAT/IGIC for explicit confirmation.

4. Connection troubleshooting and recovery​

If your agent does not list Frihet tools or returns an error on your first read, apply this recovery table:

Symptom in the agentVerifiable root causeHow to recover
401 Unauthorized error when listing invoices or clientsThe key in FRIHET_API_KEY does not start with fri_, contains extra whitespace, was revoked, or the OAuth session expiredCreate a new key in Integrations → API Keys, update your MCP client JSON file, and fully restart the agent app
403 Forbidden error when attempting a specific actionThe operation requires a higher plan tier (e.g., create_webhook requires Premium) or your user lacks module permissionsCheck your active plan in Settings → Plan & Billing and your role in Settings → Team (you can ask the agent to run permissions_me)
MCP client reports that the frihet server failed to startNode.js is not in the desktop app PATH or the local npx cache holds an outdated versionPin "@frihet/mcp-server@1.17.0" in args, add "FRIHET_MCP_DEBUG": "1" to env to inspect client logs, or switch to the remote endpoint https://mcp.frihet.io/mcp
422 error or tool rejected due to preconditionRequired issuer tax fields are missing when creating invoices, or a surface-deferred (period_close — callability: deferred) / unavailable (ksef_submit — callability: unavailable) tool was calledComplete your tax ID and fiscal address in Settings → Tax Profile and check the callability table in MCP profiles, transport, and runtime callability

Next​

Next action for your workflow​

Prefer code over conversation? The REST API exposes the same operations over HTTP/JSON.