Build on Frihet's MCP Server: A Developer's 2026 Guide

Most posts about Frihet’s MCP server explain that it exists. This one is for the people who want to build on it: developers, AI engineers, and founders wiring agents into their stack. If you have searched for an honest answer on MCP server ERP developer integration, this is the missing how-to — config, auth, a first working workflow, and the agentic patterns that earn their keep. Real tool counts, real endpoints, real config blocks you can paste.

What an MCP server is — and why an ERP exposing one matters

MCP (Model Context Protocol) is an open standard from Anthropic. It defines a common way for an AI assistant to discover and call external tools. If your agent speaks MCP and a system speaks MCP, they can work together with no bespoke glue code.

That standardization is the point. Before MCP, every “connect the AI to my business data” project meant a custom integration: hand-rolled function definitions, an auth layer, response parsing, and maintenance every time the API moved. MCP collapses that into a protocol the agent already understands.

An ERP exposing an MCP server is a bigger deal than it sounds. Your ERP is where the operational truth lives — who owes you money, what you spent, which clients are active, what tax you owe. The moment an agent can read and write that truth through a stable protocol, it stops being a chat toy and starts being an operator: reconciling, invoicing, chasing payments, prepping filings. That is the difference between AI as decoration and AI that does the work.

Frihet was built for this from the start. Every feature we ship has to answer one question: can an AI agent operate it? If it can’t, it isn’t finished. That is also the thesis behind our piece on why a developer-first ERP API is the future — the MCP server is that thesis made executable.

Frihet’s MCP server: 151 tools for your agent

The current server (v1.12.0 — the stable latest on npm, shipped 2026-06-10) exposes 151 tools grouped across tool categories, plus 11 resources and 10 guided prompts. It is published on npm as @frihet/mcp-server, available as a remote endpoint at mcp.frihet.io/mcp, and MIT-licensed — read the source, fork it, audit it.

The tool categories map onto the ERP itself: invoices (create, send, credit notes, late fees, deposits, e-invoice XML export), expenses, clients & CRM (pipeline stages, profitability, health scoring), products & quotes (including quote-to-invoice conversion), banking, fiscal models (Modelo 303, 130, 390, 180, 347), compliance (VeriFactu, TicketBAI), the Stay and POS verticals, plus time entries, recurring invoices, and webhooks.

Two MCP concepts are worth understanding before you build, because they change how an agent behaves:

• Resources are read-only reference data the agent pulls without spending an API call — current Spanish VAT and IGIC rates, the quarterly filing calendar, expense categories, your API schema. The agent has tax context before it acts, so it doesn’t ask you which VAT rate applies.
• Prompts are guided multi-step workflows. Instead of improvising a sequence, a prompt like monthly-close walks the agent through the steps in order. We covered these when v1.2 added resources, prompts, and structured output — and structured output is the unsung hero: every tool returns a defined schema, so responses are deterministically parseable instead of free text you have to regex.

Connecting Claude Desktop, Cursor, and custom agents

The whole point of MCP is that connection is configuration, not code. Here is the walkthrough for the three most common cases.

Claude Desktop

Open your claude_desktop_config.json and add Frihet under mcpServers:

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

Restart Claude Desktop. The 151 tools, 11 resources, and 10 prompts appear automatically. The server runs as a local subprocess over stdio — nothing is exposed to the network.

Cursor

Cursor reads mcp config from ~/.cursor/mcp.json (or the project-level .cursor/mcp.json). Same shape:

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

Now you can prompt Cursor’s agent to manage real business data while you code — useful when you are building an integration and want to test against your own account.

Custom agents and hosted clients

If you are building your own agent (Python, TypeScript, anything with an MCP client library) or running a hosted assistant, use the remote endpoint instead of spawning a subprocess:

https://mcp.frihet.io/mcp

Point your MCP client at that URL and pass your API key as a Bearer token (Authorization: Bearer fri_<your_key>). The same 151 tools are available over the network. This is the path for server-side agents, CI bots, and any environment where launching npx per session isn’t practical. Clients that support OAuth — Claude Desktop, Smithery, and others — can instead authenticate against the same endpoint via the OAuth 2.1 + PKCE browser flow, with no API key to manage. Note the path: the MCP endpoint is mcp.frihet.io/mcp, not the bare host.

The takeaway: whether your client is a desktop app, an IDE, or your own code, the integration surface is identical — a server name, a command or URL, and one secret.

Authentication, scopes, and keeping client data secure

For direct and npm usage there is one credential: your Frihet API key (it starts with fri_), generated in Settings → API. The hosted remote endpoint adds a second option — a first-class OAuth 2.1 + PKCE browser flow — so clients that support OAuth (Claude Desktop, Smithery) can log in without handling a key at all. A few principles:

The key is the boundary. For API-key auth, every MCP tool call carries your key on the server side — no shared service account. On the hosted endpoint you can instead use the OAuth 2.1 + PKCE authorization-code flow, which exchanges a browser login for a scoped token. Either way, the server doesn’t persist your business data beyond the request that uses it; treat the credential itself (key or token) as the thing to protect.

Scope per agent. Running a monthly-close bot and a dunning bot? Issue a separate key for each. You can revoke one without disrupting the other, and your audit trail tells you which agent did what. Least privilege is cheap here.

Keys live in env vars, never in code. Every config block above reads FRIHET_API_KEY from env, not a hardcoded string in a committed file. Keep it that way, rotate on a schedule, and revoke immediately if a laptop or CI runner is compromised — which is one click in Settings, with expiration dates if you want time-boxed access.

The MCP server doesn’t change your security model. It just makes the ERP another well-scoped API behind your key.

Building your first workflow: “create an invoice from this email”

Here is the canonical example, and it is genuinely one prompt away once you are connected.

You receive an email:

“Hi — please invoice us €2,500 for the January consulting engagement. Our company is Acme Ltd, VAT ESB12345678, [email protected]. Net 30.”

Paste it into your connected agent with: “Create a Frihet invoice from this email.”

Behind the scenes the agent does what you would do by hand, but in one pass:

1. Reads the frihet://tax/rates resource to know the applicable VAT rate — no question asked.
2. Calls client lookup to check whether Acme Ltd exists; if not, calls create client with the name, VAT ID, and email.
3. Calls create invoice with the line item, computed VAT, Net 30 terms, and the correct numbering series.
4. Returns the new invoice in structured output — number, total, due date, status — to confirm or send.

No copy-paste, no tab switching, no re-keying the VAT number. The agent did the read, the lookups, and the write through tools that share Frihet’s real calculation engine, so the tax math is the same one the app uses.

This is the atom of agentic operations. Once your agent can turn an unstructured email into a correct invoice, the bigger patterns are just compositions of the same idea.

Agentic patterns: monthly close, dunning, and expense triage

The interesting work isn’t single calls — it’s standing workflows that an agent runs on a cadence. Three that pay for themselves:

Monthly close

Trigger the monthly-close prompt and the agent walks the close in order: list unpaid invoices, flag overdue ones, categorize the month’s expenses, reconcile what the banking tools surface, and report what is still missing before the books are clean. Instead of you opening five screens on the first of the month, the agent hands you a punch list. This is the operational core of an agentic ERP that runs itself.

Dunning

Ask the agent: “Who owes me money, and how overdue?” It queries invoices, buckets them by aging (1-30 / 31-60 / 61-90 / 90+), and drafts a reminder per debtor with the right tone for each bucket. You review and approve — the agent never sends money-touching messages to third parties without your sign-off. But the “who do I chase and what do I say” overhead is gone. Pair it with our six-step guide to collecting from late payers for the templates.

Expense triage

Forward receipts and statements at the agent and let it OCR, categorize, and flag anything off — a duplicate, a wrong VAT rate, an expense that should be billable to a client. Categorization runs on your historical patterns, so triage sharpens the more you feed it.

One operational note: autonomous agent runs (the Cofounder AI loop) are a metered capability — the Business plan includes 100 runs per month, with unlimited on Enterprise. Read-and-write tool calls from your own MCP client count against your normal API usage, not agent runs. Plan your cadence accordingly.

If you want these patterns running on a schedule without a human in the loop at all, you can drive them from an orchestrator — see automating your business with Frihet, Claude, and n8n.

API + MCP together: when to call which

Frihet gives you two doors into the same building. Knowing which to use is most of the architecture decision.

Reach for the MCP server when:

• An AI agent is the caller, and the input is natural language or unstructured (an email, a chat message, a forwarded PDF).
• You want guided workflows (the prompts) and free tax context (the resources).
• You are prototyping fast and don’t want to write API plumbing.

Reach for the REST API at api.frihet.io/v1 when:

• Your code is the caller and you control the exact inputs.
• You need deterministic, high-volume, repeatable automation, or you are integrating from a platform without an MCP client.
• You are building a product surface, not an agent.

The REST API ships an OpenAPI 3.1 spec at /openapi.yaml, API-key auth, cursor pagination, field selection, and action endpoints for e-invoice XML, credit notes, and late fees. There is also an official TypeScript SDK (@frihet/sdk) and a CLI (frihet) for typed clients or terminal scripting.

Because both doors open onto the same backend, you can mix them freely. A common shape: the MCP agent handles the messy front end — parsing an email, deciding what to do — and your deterministic REST job does the bulk write or scheduled batch. The agent for judgment, the API for throughput.

Wrapping up

An MCP server is only as useful as the system behind it. Frihet’s exposes the whole ERP — 151 tools, 11 resources, 10 prompts — behind your API key (or OAuth 2.1 + PKCE on the hosted endpoint), MIT-licensed, on npm and at mcp.frihet.io/mcp. Connecting takes a few lines of JSON. The first real workflow takes one prompt. After that the ceiling is your cadence: monthly close, dunning, expense triage, run by an agent that operates your books instead of just talking about them.

Generate an API key, paste the config, and ask your agent to create an invoice from your next email. That is the whole demo.