MCP-server

Frihets MCP-server implementerer Model Context Protocol slik at AI-assistenter kan interagere direkte med ditt ERP. Opprette fakturaer, registrere utgifter, konsultere kunder eller administrere tilbud — alt fra din IDE eller terminal, i naturlig språk.

Du:      "Opprett en faktura for TechStart SL, 40 timer konsulentarbeid til 75 EUR/time, forfall 1. mars"
Claude:  Ferdig. Faktura INV-2026-089 opprettet. Totalt: 3.000,00 EUR + 21% mva = 3.630,00 EUR.

Hva du kan forvente (og hva du ikke kan)

MCP-serveren er en stateless bro mellom din AI-assistent og Frihets REST API. Hvert verktøykall oversettes til en HTTP-forespørsel til API-et.

Hva den GJØR:

Fullstendig CRUD for fakturaer, utgifter, kunder, produkter, tilbud og webhooks
Søk etter fakturaer etter kundenavn
Tilgang til referansedata (skattesatser, skattekalender, kategorier)
Veiledede arbeidsflyter (månedlig avslutning, skatteforberedelse, oppfølging av forfalte betalinger)

Hva den IKKE gjør:

OCR av dokumenter (dette gjøres av AI-assistenten i appen)
Generering av PDF-er (bruk REST API direkte: GET /v1/invoices/:id/pdf)
Betalingsbehandling (innkrevinger håndteres via Stripe Connect i appen)

Krav

Frihet-konto med API-tilgang (betalte planer)
API-nøkkel generert fra panelet

Hente API-nøkkelen

Logg inn på app.frihet.io
Gå til Innstillinger > Utviklere > API-nøkler
Klikk Opprett API-nøkkel
Kopier nøkkelen (starter med fri_) — den vises kun én gang

Installasjon

Universal (30+ agenter)

Den raskeste måten å installere MCP-serveren og forretningsferdigheten:

npx skills add Frihet-io/frihet-mcp

Fungerer med Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, og 30+ flere agenter.

MCP Registry

Serveren er registrert som io.frihet/erp i det offisielle MCP Registry. MCP-klienter som støtter registeret kan automatisk oppdage og installere det via dets kanoniske navn.

Direkte npx

npx -y @frihet/mcp-server@latest

Du trenger ikke å installere noe globalt. npx laster ned og kjører den nyeste versjonen automatisk.

Manuell konfigurasjon

Det er to tilkoblingsmoduser: lokal (serveren kjører på din maskin via npx) og ekstern (direkte tilkobling til mcp.frihet.io, uten installasjon).

Lokal (stdio)

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

Ekstern (streamable-http)

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_tu_clave_aqui"
      }
    }
  }
}

Konfigurasjon per klient

JSON-strukturen er identisk på tvers av alle klienter. Kun plasseringen av konfigurasjonsfilen endres.

Klient	Konfigurasjonsfil
Claude Code	`~/.claude/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` eller `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	VS Code-konfigurasjon eller `.cline/mcp.json`
Codex CLI	`~/.codex/config.toml` (MCP-seksjon)

tip

Hvis du bruker Claude Code, kan du legge til serveren med én enkelt kommando:

claude mcp add frihet -- npx -y @frihet/mcp-server@latest

Deretter konfigurerer du variabelen FRIHET_API_KEY i den resulterende filen ~/.claude/mcp.json.

Miljøvariabler

Variabel	Obligatorisk	Standardverdi
`FRIHET_API_KEY`	Ja	--
`FRIHET_API_URL`	Nei	`https://api.frihet.io/v1`
`FRIHET_MCP_DEBUG`	Nei	`0`

FRIHET_API_URL er nyttig hvis du peker mot et staging-miljø eller en tilpasset instans. Den må være https:// med et vertsnavn under frihet.io.
FRIHET_MCP_DEBUG=1 aktiverer debug-nivå logger (nyttig for å diagnostisere problemer).

OAuth-flyt

MCP-serveren støtter OAuth-autentisering i tillegg til manuell API-nøkkel. Når en MCP-klient starter OAuth-flyten:

Brukeren autentiserer via Firebase Auth (e-post, Google, GitHub eller Microsoft)
Klienten sender sesjonstokenet til POST /api/oauth/api-key
Serveren provisionerer en ny nøkkel fri_xxx... merket "MCP OAuth" med en utløpsdato på 365 dager
Nøkkelen brukes automatisk for påfølgende kall

Dette lar brukere koble til MCP-serveren uten å kopiere nøkler manuelt.

Tilgjengelige verktøy (44)

Serveren eksponerer 52 verktøy organisert i 7 kategorier. Hvert verktøy inkluderer strukturert output (outputSchema + structuredContent) slik at assistenter kan parse svar på en pålitelig måte, i tillegg til sikkerhets- og innholdsannotasjoner. Tospråklig (EN/ES).

Fakturaer (6 verktøy)

Verktøy	Beskrivelse	Nøkkelparametere
`list_invoices`	Viser fakturaer med paginering	`limit`, `offset`
`get_invoice`	Henter en faktura etter ID	`id`
`create_invoice`	Oppretter en faktura med detaljlinjer	`clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`
`update_invoice`	Oppdaterer felt i en faktura (delvis)	`id`, og alle felt som skal endres
`delete_invoice`	Sletter en faktura permanent	`id`
`search_invoices`	Søker etter fakturaer etter kundenavn	`clientName`, `limit`, `offset`

Mulige fakturastatuser: utkast, sendt, betalt, forfalt, kansellert

Utgifter (5 verktøy)

Verktøy	Beskrivelse	Nøkkelparametere
`list_expenses`	Viser utgifter med paginering	`limit`, `offset`
`get_expense`	Henter en utgift etter ID	`id`
`create_expense`	Registrerer en ny utgift	`description`, `amount`, `category`, `date`, `vendor`, `taxDeductible`
`update_expense`	Endrer en eksisterende utgift (delvis)	`id`, og alle felt som skal endres
`delete_expense`	Sletter en utgift permanent	`id`

Kunder (5 verktøy)

Verktøy	Beskrivelse	Nøkkelparametere
`list_clients`	Viser alle kunder	`limit`, `offset`
`get_client`	Henter en kunde etter ID	`id`
`create_client`	Registrerer en ny kunde	`name`, `email`, `phone`, `taxId`, `address` (street, city, state, postalCode, country)
`update_client`	Oppdaterer kundedata (delvis)	`id`, og alle felt som skal endres
`delete_client`	Sletter en kunde permanent	`id`

Produkter (5 verktøy)

Verktøy	Beskrivelse	Nøkkelparametere
`list_products`	Viser produkter og tjenester	`limit`, `offset`
`get_product`	Henter et produkt etter ID	`id`
`create_product`	Oppretter et produkt eller en tjeneste	`name`, `unitPrice`, `description`, `taxRate`
`update_product`	Endrer et eksisterende produkt (delvis)	`id`, og alle felt som skal endres
`delete_product`	Sletter et produkt permanent	`id`

Tilbud (5 verktøy)

Verktøy	Beskrivelse	Nøkkelparametere
`list_quotes`	Viser tilbud	`limit`, `offset`
`get_quote`	Henter et tilbud etter ID	`id`
`create_quote`	Oppretter et tilbud for en kunde	`clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status`
`update_quote`	Endrer et tilbud (delvis)	`id`, og alle felt som skal endres
`delete_quote`	Sletter et tilbud permanent	`id`

Mulige tilbudsstatuser: utkast, sendt, akseptert, avvist, utløpt

Webhooks (5 verktøy)

Verktøy	Beskrivelse	Nøkkelparametere
`list_webhooks`	Viser konfigurerte webhooks	`limit`, `offset`
`get_webhook`	Henter webhook-konfigurasjon	`id`
`create_webhook`	Registrerer et webhook-endepunkt	`url`, `events[]`, `active`, `secret`
`update_webhook`	Endrer en eksisterende webhook	`id`, og alle felt som skal endres
`delete_webhook`	Sletter en webhook permanent	`id`

Tilgjengelige webhook-hendelser: invoice.created, invoice.updated, invoice.deleted, invoice.paid, expense.created, expense.updated, expense.deleted, client.created, client.updated, client.deleted, product.created, product.updated, product.deleted, quote.accepted. Se Webhooks for nyttelastformat og HMAC-verifisering.

Tilgjengelige ressurser (8)

MCP-ressurser er referansedata som assistenten kan konsultere uten å gjøre API-kall. De er statiske og alltid tilgjengelige.

Ressurs	URI	Beskrivelse
API-skjema	`frihet://api/schema`	Sammendrag av endepunkter, autentisering, rate limits og feilkoder
Skattesatser	`frihet://tax/rates`	mva (21/10/4%), IGIC (7/3/0%), IPSI, intra-europeisk, IRPF (15%/7%)
Skattekalender	`frihet://tax/calendar`	Kvartalsvise innleveringsfrister (Model 303, 130, 420, 390)
Utgiftskategorier	`frihet://config/expense-categories`	8 kategorier med fradragsregler og skattebehandling
Fakturastatuser	`frihet://config/invoice-statuses`	Statusflyt (utkast, sendt, betalt, forfalt, kansellert) med triggere
Leverandører	`frihet://config/vendors`	Liste over registrerte leverandører med skatte- og kontaktopplysninger
Aktive integrasjoner	`frihet://config/integrations`	Status for tilkoblede integrasjoner (Stripe, Shopify, etc.)
Forretningskonfigurasjon	`frihet://config/business`	Selskapets skattedata, skattesone, valuta og preferanser

Tilgjengelige prompter (7)

Promptere er veiledede arbeidsflyter som assistenten utfører trinn for trinn. De kalles opp etter navn.

Prompt	Beskrivelse	Parametere
`monthly-close`	Månedlig avslutning: gjennomgår ubetalte fakturaer, kategoriserer utgifter, verifiserer skatteforpliktelser, genererer oppsummering	`month` (valgfritt)
`onboard-client`	Kundeopptak: bestemmer skattesats basert på lokasjon, oppretter registeroppføring, genererer velkomsttilbud	`clientName`, `country`, `region`
`quarterly-tax-prep`	Kvartalsvis skatteforberedelse: samler fakturaer, beregner mva/IGIC, genererer forhåndsvisning av Model 303/130	`quarter`, `fiscalZone`
`overdue-followup`	Oppfølging av forfalte betalinger: identifiserer forfalte fakturaer, grupperer etter kunde, utarbeider innkrevelsesmeldinger	—
`expense-batch`	Batchbehandling av utgifter: kategoriserer, anvender skatter, verifiserer fradragsrett, oppretter med bekreftelse	`fiscalZone`
`vendor-analysis`	Leverandøranalyse: grupperer utgifter etter leverandør, beregner totaler, identifiserer trender og sparemuligheter	`period` (valgfritt)
`business-health`	Forretningshelse-diagnose: nøkkel-KPI-er, sammenligning med forrige måned, varsler og handlingsorienterte anbefalinger	`month` (valgfritt)

tip

Du kan påkalle en prompt direkte: "Utfør månedlig avslutning for februar" eller "Forbered skattene for Q1".

Eksempler på bruk

Dette er reelle forespørsler i naturlig språk som assistenten oversetter til MCP-verktøykall.

Opprette en faktura

"Opprett en faktura for Acme SL med 10 timer konsulentarbeid til 95 EUR/time, forfall 15. mars"

Assistenten kaller create_invoice med clientName: "Acme SL", en detaljlinje (10 x 95) og dueDate: "2026-03-15". Den beregner totalen automatisk.

Registrere en utgift

"Registrer en utgift på 59.99 EUR for Adobe Creative Cloud, kategori programvare, fradragsberettiget"

Den kaller create_expense med description, amount: 59.99, category: "software" og taxDeductible: true.

Søke etter fakturaer fra en kunde

"Søk etter alle fakturaer fra TechStart SL"

Den kaller search_invoices med clientName: "TechStart SL" og returnerer treffene med deres totaler og statuser.

Konsultere forfalte betalinger

"Vis meg alle ubetalte fakturaer"

Den kaller list_invoices og filtrerer etter status: "sent" eller "overdue", og viser de forfalte fakturaene sortert etter beløp.

Registrere en kunde

"Ny kunde: Design Studio SL, NIF B87654321, e-post hola@designstudio.es, Madrid 28001"

Den kaller create_client med navn, NIF, e-post og adresse.

Konfigurere automatisering

"Opprett en webhook for å varsle https://mi-app.com/hook når en faktura blir betalt"

Den kaller create_webhook med url og events: ["invoice.paid"].

Oppdatere et produkt

"Øk prisen for konsulenttimen til 85 EUR"

Den kaller update_product med produktets id og unitPrice: 85. Kun det angitte feltet endres.

Observabilitet

MCP-server v1.5.1 inkluderer strukturert logging og verktøymetriker.

Strukturert logging

Alle logger sendes ut som JSON til stderr (MCP bruker stdout for protokollmeldinger). Hver oppføring inkluderer:

level: debug, info, warn, error
service: alltid frihet-mcp
timestamp: ISO 8601
tool: verktøyets navn (når aktuelt)
operation: operasjonstype (tool_call, api_call, api_retry, startup, shutdown_metrics)
durationMs: utførelsestid i millisekunder
error: feildetaljer (message, code, statusCode)

Aktiver debug-logger med FRIHET_MCP_DEBUG=1.

Verktøymetriker

Serveren logger i minnet kall til hvert verktøy: antall kall, feil og gjennomsnittlig varighet. Når serveren avsluttes (SIGINT/SIGTERM), sendes en oppsummering ut:

{
  "level": "info",
  "message": "Nedstenging etter 3600s — 42 kall, 1 feil",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}

Automatisk rate-limit gjenforsøk

Når API-et svarer med 429, prøver serveren automatisk igjen med eksponensiell backoff (opptil 3 gjenforsøk). Gjenforsøkene logges:

{
  "level": "warn",
  "message": "Rate begrenset, prøver igjen GET /invoices (forsøk 2, forsinkelse 2000ms)",
  "operation": "api_retry"
}

Du trenger ikke å håndtere rate limiting manuelt — serveren gjør det for deg.

Transport

Frihets MCP-server støtter to transportmoduser. Begge eksponerer de samme 52 verktøyene, 11 ressursene og 10 promptene.

Lokal (stdio)

Serveren kjører som en lokal prosess på maskinen din. Kommunikasjonen mellom MCP-klienten og serveren bruker standard inn-/utgang (stdin/stdout).

Krever: Node.js installert (lastes ned automatisk via npx)
Fordel: Lavere ventetid, fungerer uten internettforbindelse (unntatt for API-kallene)
Bruksområde: Daglig utvikling, intensiv bruk, bedriftsmiljøer med nettverksrestriksjoner

Ekstern (streamable-http)

Serveren kjører på Cloudflare Workers. Din MCP-klient kobler direkte til https://mcp.frihet.io/mcp via HTTP.

Krever: Kun internettforbindelse
Fordel: Ingen lokal installasjon, ingen avhengigheter, fungerer på alle enheter
Bruksområde: Rask konfigurasjon, team som foretrekker å ikke installere pakker, klienter som kun støtter HTTP-transport

info

Hvis din MCP-klient ikke støtter streamable-http (noen eldre klienter støtter kun stdio), bruk lokal modus.

Feilhåndtering

Rate limiting

API-et tillater 100 forespørsler per minutt per nøkkel. Hvis grensen overskrides, returnerer serveren en 429-feil med ventetiden i retryAfter.

MCP-serveren håndterer rate limiting automatisk med eksponensiell backoff: den prøver forespørselen igjen etter å ha ventet den angitte tiden, uten brukerinvolvering. Maksimalt 3 gjenforsøk.

Autentiseringsfeil

Kode	Årsak	Løsning
`401`	Ugyldig, utløpt eller ikke oppgitt API-nøkkel	Verifiser at nøkkelen i din konfigurasjon starter med `fri_` og ikke er utløpt
`403`	Nøkkelen har ikke tilgang til denne ressursen	Generer en ny nøkkel med de nødvendige tillatelsene

Andre feil

Kode	Beskrivelse
`400`	Feil parametere eller manglende obligatoriske felt
`404`	Den forespurte ressursen eksisterer ikke
`408`	Forespørsel timeout (30 sekunder)
`413`	Forespørselens brødtekst overskrider 1 MB
`422`	Gyldige data, men kan ikke behandles (f.eks. skatteprofil ikke konfigurert)
`429`	Grense for forespørsler overskredet (prøves igjen automatisk)
`500`	Intern serverfeil

Alle feil returnerer en beskrivende tospråklig melding (EN/ES) slik at assistenten kan kommunisere problemet til brukeren på en klar måte.

Grenser

Konsept	Verdi
Forespørsler per minutt	100 per API-nøkkel
Resultater per side	100 maksimum (50 som standard)
Forespørselens brødtekst	1 MB maksimum
Webhook-nyttelast	100 KB maksimum
Webhooks per konto	20 maksimum
Forespørsel timeout	30 sekunder
Gjenforsøk for rate limit	3 maksimum

Forskjell med REST API

	MCP-server	REST API
Rettet mot	AI-assistenter (Claude, Cursor, Windsurf)	Applikasjoner, skript, integrasjoner
Kommunikasjon	Naturlig språk via MCP-klienten	Direkte HTTP/JSON
Autentisering	Miljøvariabel i klientkonfigurasjonen (eller OAuth)	Header `X-API-Key` eller `Authorization: Bearer`
Format	Formatert tekst + strukturert output for assistenten	Rå JSON
Rate limiting	Håndteres automatisk (eksponensiell backoff, 3 gjenforsøk)	Manuell (konsumenten må implementere gjenforsøk)
Observabilitet	Strukturert logging + metrikker per verktøy	Forespørselslogger via `X-Request-Id`
Bruksområde	Kommunisere med ditt ERP fra IDE-en	Bygge programmatiske integrasjoner

Internt oversetter MCP-serveren hvert verktøykall til en forespørsel til REST API-et. Den dupliserer ikke logikk — det er en stateless bro.

Utvikling

For å bidra eller kjøre serveren i utviklingsmodus:

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Kjør lokalt:

FRIHET_API_KEY=fri_tu_clave node dist/index.js

Kjør med debug-logger:

FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_tu_clave node dist/index.js

Test med MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Relaterte ressurser

REST API — Komplett referanse for endepunkter, autentisering og feilkoder
Webhooks — Tilgjengelige hendelser, HMAC-SHA256 verifisering og gjenforsøksstrategi
Skill for Claude Code — Forretningsintelligenslag over MCP-serveren
Kildekode (GitHub) — MCP-serverens repository
npm-pakke — @frihet/mcp-server@1.5.1
MCP Registry — io.frihet/erp
Eksternt endepunkt — MCP-server hostet på Cloudflare Workers
MCP-spesifikasjon — Protokolldokumentasjon

Forrige: Webhooks | Neste: Skill for Claude Code

Hva du kan forvente (og hva du ikke kan)​

Krav​

Hente API-nøkkelen​

Installasjon​

Universal (30+ agenter)​

MCP Registry​

Direkte npx​

Manuell konfigurasjon​

Lokal (stdio)​

Ekstern (streamable-http)​

Konfigurasjon per klient​

Miljøvariabler​

OAuth-flyt​

Tilgjengelige verktøy (44)​

Fakturaer (6 verktøy)​

Utgifter (5 verktøy)​

Kunder (5 verktøy)​

Produkter (5 verktøy)​

Tilbud (5 verktøy)​

Webhooks (5 verktøy)​

Tilgjengelige ressurser (8)​

Tilgjengelige prompter (7)​

Eksempler på bruk​

Opprette en faktura​

Registrere en utgift​

Søke etter fakturaer fra en kunde​

Konsultere forfalte betalinger​

Registrere en kunde​

Konfigurere automatisering​

Oppdatere et produkt​

Observabilitet​

Strukturert logging​

Verktøymetriker​

Automatisk rate-limit gjenforsøk​

Transport​

Lokal (stdio)​

Ekstern (streamable-http)​

Feilhåndtering​

Rate limiting​

Autentiseringsfeil​

Andre feil​

Grenser​

Forskjell med REST API​

Utvikling​

Relaterte ressurser​

Hva du kan forvente (og hva du ikke kan)

Krav

Hente API-nøkkelen

Installasjon

Universal (30+ agenter)

MCP Registry

Direkte npx

Manuell konfigurasjon

Lokal (stdio)

Ekstern (streamable-http)

Konfigurasjon per klient

Miljøvariabler

OAuth-flyt

Tilgjengelige verktøy (44)

Fakturaer (6 verktøy)

Utgifter (5 verktøy)

Kunder (5 verktøy)

Produkter (5 verktøy)

Tilbud (5 verktøy)

Webhooks (5 verktøy)

Tilgjengelige ressurser (8)

Tilgjengelige prompter (7)

Eksempler på bruk

Opprette en faktura

Registrere en utgift

Søke etter fakturaer fra en kunde

Konsultere forfalte betalinger

Registrere en kunde

Konfigurere automatisering

Oppdatere et produkt

Observabilitet

Strukturert logging

Verktøymetriker

Automatisk rate-limit gjenforsøk

Transport

Lokal (stdio)

Ekstern (streamable-http)

Feilhåndtering

Rate limiting

Autentiseringsfeil

Andre feil

Grenser

Forskjell med REST API

Utvikling

Relaterte ressurser