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:
| Decision | Local option (stdio) | Remote option (streamable-http) |
|---|---|---|
| How it connects | Runs npx -y @frihet/mcp-server@1.17.0 on your machine | Connects over HTTPS to https://mcp.frihet.io/mcp (zero local packages installed) |
| Authentication | FRIHET_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 processes | 165 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 tools | Out 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
- Sign in to app.frihet.io
- Go to Integrations and open the API Keys tab
- 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 invoiceF-2026-0001(1,815.00 EUR, statuspaid). - If your account is new and still empty: the MCP server responds
200 OKwithdata: []andtotal: 0. That empty response still confirms that yourfri_...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 agent | Verifiable root cause | How to recover |
|---|---|---|
401 Unauthorized error when listing invoices or clients | The key in FRIHET_API_KEY does not start with fri_, contains extra whitespace, was revoked, or the OAuth session expired | Create 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 action | The operation requires a higher plan tier (e.g., create_webhook requires Premium) or your user lacks module permissions | Check 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 start | Node.js is not in the desktop app PATH or the local npx cache holds an outdated version | Pin "@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 precondition | Required issuer tax fields are missing when creating invoices, or a surface-deferred (period_close — callability: deferred) / unavailable (ksef_submit — callability: unavailable) tool was called | Complete 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
- If you run Hermes Agent in a terminal or server: follow the dedicated Hermes Agent with Frihet guide.
- If you want to inspect all 157 tools, 11 resources, and 10 prompts: browse the full MCP Server reference.
- If you need signed real-time events in your own backend: continue with Webhooks and HMAC-SHA256 verification.
Prefer code over conversation? The REST API exposes the same operations over HTTP/JSON.