Skip to main content

MCP-palvelin

Frihetin MCP-palvelin toteuttaa Model Context Protocol -protokollan, jotta tekoälyavustajat voivat olla suoraan vuorovaikutuksessa ERP-järjestelmäsi kanssa. Luo laskuja, rekisteröi kuluja, tarkastele asiakkaita tai hallinnoi tarjouksia – kaikki IDE:stäsi tai terminaalista, luonnollisella kielellä.

Nykyinen versio: 1.5.1 | 52 työkalua | 11 resurssia | 10 kehote | Strukturoitu tuloste | Yhteensopiva yli 30 tekoälyagentin kanssa.

Tu:      "Crea una factura para TechStart SL, 40 horas de consultoria a 75 EUR/hora, vencimiento 1 marzo"
Claude:  Hecho. Factura INV-2026-089 creada. Total: 3.000,00 EUR + 21% IVA = 3.630,00 EUR.

Mitä odottaa (ja mitä ei)​

MCP-palvelin on tilaton silta tekoälyavustajasi ja Frihetin REST API:n välillä. Jokainen työkalukutsu muunnetaan HTTP-pyynnöksi API:lle.

Mitä SE tekee:

  • Täysi CRUD laskuille, kuluille, asiakkaille, tuotteille, tarjouksille ja webhoakeille
  • Laskujen haku asiakkaan nimen perusteella
  • Pääsy viitetietoihin (verokannat, verokalenteri, kategoriat)
  • Opastetut työnkulut (kuukausisulku, verovalmistelu, erääntyneiden seuranta)

Mitä SE EI tee:

  • Asiakirjojen OCR (sen tekee tekoälyavustaja sovelluksen sisällä)
  • PDF-tiedostojen luonti (käytä REST API:a suoraan: GET /v1/invoices/:id/pdf)
  • Maksujen käsittely (maksut käsitellään Stripe Connectin kautta sovelluksessa)

Vaatimukset​

  • Frihet-tili API-yhteydellä (maksulliset suunnitelmat)
  • API-avain luotu paneelista

API-avaimen hankkiminen​

  1. Kirjaudu sisään osoitteeseen app.frihet.io
  2. Siirry kohtaan Asetukset > Kehittäjät > API-avaimet
  3. Paina Luo API-avain
  4. Kopioi avain (alkaa fri_) – se näytetään vain kerran

Asennus​

Universaali (yli 30 agenttia)​

Nopein tapa asentaa MCP-palvelin ja liiketoimintataito:

npx skills add Frihet-io/frihet-mcp

Toimii Claude Coden, Cursorin, Copilotin, Codexin, Windsurfin, Gemini CLI:n, Goosen, Roo Coden ja yli 30 muun agentin kanssa.

MCP Registry​

Palvelin on rekisteröity nimellä io.frihet/erp virallisessa MCP Registryssa. Rekisteriä tukevat MCP-asiakasohjelmat voivat löytää ja asentaa sen automaattisesti kanonisella nimellä.

Suora npx​

npx -y @frihet/mcp-server@latest

Sinun ei tarvitse asentaa mitään globaalisti. npx lataa ja suorittaa uusimman version automaattisesti.

Manuaalinen konfigurointi​

Yhteyden muodostamiseen on kaksi tilaa: paikallinen (palvelin suoritetaan koneellasi npx:n kautta) ja etäinen (suora yhteys osoitteeseen mcp.frihet.io, ilman asennusta).

Paikallinen (stdio)​

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

Etäinen (streamable-http)​

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

Asiakaskohtainen konfigurointi​

JSON-rakenne on identtinen kaikissa asiakasohjelmissa. Vain konfigurointitiedoston sijainti muuttuu.

AsiakasohjelmaKonfigurointitiedosto
Claude Code~/.claude/mcp.json
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor.cursor/mcp.json o ~/.cursor/mcp.json
Windsurf~/.windsurf/mcp.json
ClineConfiguracion de VS Code o .cline/mcp.json
Codex CLI~/.codex/config.toml (seccion MCP)
tip

Jos käytät Claude Codea, voit lisätä palvelimen yhdellä komennolla:

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

Määritä sitten FRIHET_API_KEY-muuttuja tuloksena syntyneeseen ~/.claude/mcp.json-tiedostoon.

Ympäristömuuttujat​

MuuttujaPakollinenOletusarvo
FRIHET_API_KEYKyllä--
FRIHET_API_URLEihttps://api.frihet.io/v1
FRIHET_MCP_DEBUGEi0
  • FRIHET_API_URL on hyödyllinen, jos kohdistat sen esittely-ympäristöön tai mukautettuun instanssiin. Sen tulee olla https:// ja isäntänimen frihet.io-aliverkossa.
  • FRIHET_MCP_DEBUG=1 aktivoi debug-tason lokit (hyödyllinen ongelmien diagnosoinnissa).

OAuth-kulku​

MCP-palvelin tukee OAuth-autentikointia manuaalisen API-avaimen lisäksi. Kun MCP-asiakasohjelma käynnistää OAuth-kulun:

  1. Käyttäjä todentaa itsensä Firebase Authin kautta (sähköposti, Google, GitHub tai Microsoft)
  2. Asiakasohjelma lähettää istuntotunnuksen osoitteeseen POST /api/oauth/api-key
  3. Palvelin antaa uuden fri_xxx... -avaimen, joka on merkitty "MCP OAuth" ja jonka vanhenemisaika on 365 päivää
  4. Avainta käytetään automaattisesti myöhemmissä kutsuissa

Tämän ansiosta käyttäjät voivat yhdistää MCP-palvelimeen kopioimatta avaimia manuaalisesti.

Käytettävissä olevat työkalut (44)​

Palvelin tarjoaa 52 työkalua, jotka on järjestetty 7 luokkaan. Jokainen työkalu sisältää strukturoidun tulosteen (outputSchema + structuredContent), jotta avustajat voivat jäsentää vastaukset luotettavasti, sekä turvallisuus- ja sisältömerkinnät. Kaksikielinen (EN/ES).

Laskut (6 työkalua)​

TyökaluKuvausAvainparametrit
list_invoicesListaa laskut sivutuksellalimit, offset
get_invoiceHakee laskun ID:n perusteellaid
create_invoiceLuo laskun rivikohtineenclientName, items[] (description, quantity, unitPrice), status, dueDate, notes, taxRate
update_invoicePäivittää laskun kenttiä (osittain)id, y cualquier campo a modificar
delete_invoicePoistaa laskun pysyvästiid
search_invoicesHakee laskuja asiakkaan nimen perusteellaclientName, limit, offset

Laskun mahdolliset tilat: luonnos, lähetetty, maksettu, erääntynyt, peruutettu

Kulut (5 työkalua)​

TyökaluKuvausAvainparametrit
list_expensesListaa kulut sivutuksellalimit, offset
get_expenseHakee kulun ID:n perusteellaid
create_expenseRekisteröi uuden kulundescription, amount, category, date, vendor, taxDeductible
update_expenseMuokkaa olemassa olevaa kulua (osittain)id, y cualquier campo a modificar
delete_expensePoistaa kulun pysyvästiid

Asiakkaat (5 työkalua)​

TyökaluKuvausAvainparametrit
list_clientsListaa kaikki asiakkaatlimit, offset
get_clientHakee asiakkaan ID:n perusteellaid
create_clientRekisteröi uuden asiakkaanname, email, phone, taxId, address (street, city, state, postalCode, country)
update_clientPäivittää asiakkaan tietoja (osittain)id, y cualquier campo a modificar
delete_clientPoistaa asiakkaan pysyvästiid

Tuotteet (5 työkalua)​

TyökaluKuvausAvainparametrit
list_productsListaa tuotteet ja palvelutlimit, offset
get_productHakee tuotteen ID:n perusteellaid
create_productLuo tuotteen tai palvelunname, unitPrice, description, taxRate
update_productMuokkaa olemassa olevaa tuotetta (osittain)id, y cualquier campo a modificar
delete_productPoistaa tuotteen pysyvästiid

Tarjoukset (5 työkalua)​

TyökaluKuvausAvainparametrit
list_quotesListaa tarjouksetlimit, offset
get_quoteHakee tarjouksen ID:n perusteellaid
create_quoteLuo tarjouksen asiakkaalleclientName, items[] (description, quantity, unitPrice), validUntil, notes, status
update_quoteMuokkaa tarjousta (osittain)id, y cualquier campo a modificar
delete_quotePoistaa tarjouksen pysyvästiid

Tarjouksen mahdolliset tilat: luonnos, lähetetty, hyväksytty, hylätty, vanhentunut

Webhookit (5 työkalua)​

TyökaluKuvausAvainparametrit
list_webhooksListaa konfiguroidut webhookitlimit, offset
get_webhookHakee webhookin konfiguraationid
create_webhookRekisteröi webhook-endpointinurl, events[], active, secret
update_webhookMuokkaa olemassa olevaa webhookiaid, y cualquier campo a modificar
delete_webhookPoistaa webhookin pysyvästiid

Käytettävissä olevat webhook-tapahtumat: 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. Katso Webhookit payloadin muodon ja HMAC-varmistuksen osalta.

Käytettävissä olevat resurssit (8)​

MCP-resurssit ovat viitetietoja, joita avustaja voi kysyä tekemättä API-kutsuja. Ne ovat staattisia ja aina saatavilla.

ResurssiURIKuvaus
API-skeemafrihet://api/schemaYhteenveto endpointeista, autentikoinnista, nopeusrajoituksista ja virhekoodeista
Verokannatfrihet://tax/ratesALV (21/10/4%), IGIC (7/3/0%), IPSI, yhteisönsisäinen, IRPF (15%/7%)
Verokalenterifrihet://tax/calendarNeljännesvuosittaiset ilmoituspäivät (Malli 303, 130, 420, 390)
Kululuokatfrihet://config/expense-categories8 kategoriaa vähennysoikeussäännöillä ja verokäsittelyllä
Laskun tilatfrihet://config/invoice-statusesTilojen kulku (luonnos, lähetetty, maksettu, erääntynyt, peruutettu) triggereineen
Toimittajatfrihet://config/vendorsLuettelo rekisteröidyistä toimittajista verotustietoineen ja yhteystietoineen
Aktiiviset integraatiotfrihet://config/integrationsYhdistettyjen integraatioiden tila (Stripe, Shopify, jne.)
Liiketoimintakonfiguraatiofrihet://config/businessYrityksen verotustiedot, verotusalue, valuutta ja asetukset

Käytettävissä olevat kehotteet (7)​

Kehotteet ovat ohjattuja työnkulkuja, jotka avustaja suorittaa askel askeleelta. Niitä kutsutaan nimellä.

KehoteKuvausParametrit
monthly-closeKuukausisulku: tarkistaa maksamattomat laskut, luokittelee kulut, tarkistaa verovelvoitteet, luo yhteenvedonmonth (valinnainen)
onboard-clientAsiakkaan käyttöönotto: määrittää verokannan sijainnin perusteella, luo rekisterin, luo tervetuliaistarjouksenclientName, country, region
quarterly-tax-prepNeljännesvuosittainen verovalmistelu: kerää laskut, laskee ALV/IGIC, luo esikatselun Mallista 303/130quarter, fiscalZone
overdue-followupErääntyneiden seuranta: tunnistaa erääntyneet laskut, ryhmittelee asiakkaan mukaan, laatii perintäviestejä—
expense-batchKulujen eräkäsittely: luokittelee, soveltaa veroja, tarkistaa vähennyskelpoisuuden, luo vahvistuksellafiscalZone
vendor-analysisToimittaja-analyysi: ryhmittelee kulut toimittajan mukaan, laskee summat, tunnistaa trendit ja säästömahdollisuudetperiod (valinnainen)
business-healthLiiketoiminnan terveystarkastus: keskeiset KPI:t, vertailu edelliseen kuukauteen, hälytykset ja toimivat suosituksetmonth (valinnainen)
tip

Voit kutsua kehotteen suoraan: "Suorita helmikuun kuukausisulku" tai "Valmistele Q1:n verot".

Käyttöesimerkit​

Nämä ovat todellisia luonnollisen kielen pyyntöjä, jotka avustaja kääntää MCP-työkalukutsuiksi.

Laskun luominen​

"Crea una factura para Acme SL con 10 horas de consultoria a 95 EUR/hora, vencimiento 15 de marzo"

Avustaja kutsuu create_invoice:n clientName: "Acme SL":llä, rivikohteella (10 x 95) ja dueDate: "2026-03-15":llä. Se laskee kokonaissumman automaattisesti.

Kulun rekisteröiminen​

"Registra un gasto de 59.99 EUR en Adobe Creative Cloud, categoria software, deducible"

Kutsuu create_expense:n description:lla, amount: 59.99:llä, category: "software":lla ja taxDeductible: true:lla.

Asiakkaan laskujen hakeminen​

"Busca todas las facturas de TechStart SL"

Kutsuu search_invoices:n clientName: "TechStart SL":llä ja palauttaa osumat niiden summien ja tilojen kanssa.

Erääntyneiden tarkastelu​

"Muestrame todas las facturas sin pagar"

Kutsuu list_invoices:n ja suodattaa status: "sent" tai "overdue" perusteella, näyttäen erääntyneet laskut summan mukaan järjestettynä.

Asiakkaan luominen​

"Nuevo cliente: Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"

Kutsuu create_client:n nimellä, NIF:llä, sähköpostilla ja osoitteella.

Automaation konfigurointi​

"Crea un webhook para notificar a https://mi-app.com/hook cuando se pague una factura"

Kutsuu create_webhook:n url:lla ja events: ["invoice.paid"]:llä.

Tuotteen päivittäminen​

"Sube el precio de la hora de consultoria a 85 EUR"

Kutsuu update_product:n tuotteen id:llä ja unitPrice: 85:llä. Vain ilmoitettu kenttä muokataan.

Observoitavuus​

MCP-palvelin v1.5.1 sisältää strukturoidun lokituksen ja työkalujen metadatiedot.

Strukturoitu lokitus​

Kaikki lokit lähetetään JSON-muodossa stderr-virtaan (MCP käyttää stdoutia protokollaviesteihin). Jokainen merkintä sisältää:

  • level: debug, info, warn, error
  • service: aina frihet-mcp
  • timestamp: ISO 8601
  • tool: työkalun nimi (tarvittaessa)
  • operation: toiminnon tyyppi (tool_call, api_call, api_retry, startup, shutdown_metrics)
  • durationMs: suoritusaika millisekunteina
  • error: virheen tiedot (viesti, koodi, statusCode)

Aktivoi debug-lokit FRIHET_MCP_DEBUG=1:llä.

Työkalujen metadatiedot​

Palvelin tallentaa muistiin jokaisen työkalukutsun: kutsujen määrä, virheet ja keskimääräinen kesto. Palvelimen sammutuksen yhteydessä (SIGINT/SIGTERM) annetaan yhteenveto:

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

Automaattinen nopeusrajoituksen uusintayritys​

Kun API vastaa 429:llä, palvelin yrittää automaattisesti uudelleen eksponentiaalisella viiveellä (enintään 3 uusintayritystä). Uusintayritykset kirjataan lokiin:

{
  "level": "warn",
  "message": "Rate limited, retrying GET /invoices (attempt 2, delay 2000ms)",
  "operation": "api_retry"
}

Sinun ei tarvitse hallita nopeusrajoitusta manuaalisesti – palvelin tekee sen puolestasi.

Siirto​

Frihetin MCP-palvelin tukee kahta siirtotilaa. Molemmat tarjoavat samat 52 työkalua, 11 resurssia ja 10 kehote.

Paikallinen (stdio)​

Palvelin suoritetaan paikallisena prosessina koneellasi. MCP-asiakasohjelman ja palvelimen välinen tiedonsiirto käyttää standardisyötettä/ulostuloa (stdin/stdout).

  • Vaatii: Node.js asennettuna (latautuu automaattisesti npx:n kautta)
  • Etu: Pienempi latenssi, toimii ilman internetyhteyttä (paitsi API-kutsujen osalta)
  • Käyttötapaus: Päivittäinen kehitys, intensiivinen käyttö, yritysympäristöt verkon rajoituksilla

Etäinen (streamable-http)​

Palvelin suoritetaan Cloudflare Workersissa. MCP-asiakasohjelmasi yhdistää suoraan osoitteeseen https://mcp.frihet.io/mcp HTTP:n kautta.

  • Vaatii: Vain internetyhteyden
  • Etu: Ei paikallista asennusta, ei riippuvuuksia, toimii millä tahansa laitteella
  • Käyttötapaus: Nopea konfigurointi, tiimit jotka mieluummin eivät asenna paketteja, asiakasohjelmat jotka tukevat vain HTTP-siirtoa
info

Jos MCP-asiakasohjelmasi ei tue streamable-http:tä (jotkut vanhat asiakasohjelmat tukevat vain stdio:ta), käytä paikallista tilaa.

Virheiden käsittely​

Nopeusrajoitus​

API sallii 100 pyyntöä minuutissa avainta kohti. Jos raja ylittyy, palvelin palauttaa virheen 429 odotusajan kanssa retryAfter-otsakkeessa.

MCP-palvelin hallitsee nopeusrajoitusta automaattisesti eksponentiaalisella viiveellä: se yrittää pyyntöä uudelleen ilmoitetun ajan odotuksen jälkeen, ilman käyttäjän toimenpiteitä. Enintään 3 uusintayritystä.

Autentikointivirheet​

KoodiSyyRatkaisu
401API-avain virheellinen, vanhentunut tai sitä ei ole annettuTarkista, että asetuksissasi oleva avain alkaa fri_:llä eikä ole vanhentunut
403Avaimella ei ole oikeuksia tähän resurssiinLuo uusi avain tarvittavilla oikeuksilla

Muut virheet​

KoodiKuvaus
400Virheelliset parametrit tai puuttuvat pakolliset kentät
404Pyydettyä resurssia ei ole olemassa
408Pyyntö aikakatkaistu (30 sekuntia)
413Pyynnön runko ylittää 1 MB
422Tiedot kelvollisia, mutta niitä ei voida käsitellä (esim. veroprofiilia ei ole määritetty)
429Pyyntöjen raja ylitetty (yrittää uudelleen automaattisesti)
500Palvelimen sisäinen virhe

Kaikki virheet palauttavat kuvaavan kaksikielisen (EN/ES) viestin, jotta avustaja voi kommunikoida ongelman käyttäjälle selkeästi.

Rajoitukset​

KonseptiArvo
Pyyntöä minuutissa100 per API-avain
Tuloksia per sivu100 maksimi (50 oletuksena)
Pyynnön runko1 MB maksimi
Webhook-payload100 KB maksimi
Webhookkeja per tili20 maksimi
Pyyntöaikakatkaisu30 sekuntia
Uusintayritykset nopeusrajoituksen vuoksi3 maksimi

Ero REST API:sta​

MCP-palvelinREST API
SuunnattuTekoälyavustajat (Claude, Cursor, Windsurf)Sovellukset, skriptit, integraatiot
ViestintäLuonnollinen kieli MCP-asiakasohjelman kauttaSuora HTTP/JSON
AutentikointiYmpäristömuuttuja asiakasohjelman asetuksissa (tai OAuth)Otsikko X-API-Key tai Authorization: Bearer
MuotoMuotoiltu teksti + strukturoitu tuloste avustajalleRaaka JSON
NopeusrajoitusHallitaan automaattisesti (eksponentiaalinen viive, 3 uusintayritystä)Manuaalinen (kuluttajan on toteutettava uusintayritykset)
ObservoitavuusStrukturoitu lokitus + metadatiedot työkalukohtaisestiPyyntölokit X-Request-Id:n kautta
KäyttötapausKeskustelu ERP:n kanssa IDE:stäOhjelmallisten integraatioiden rakentaminen

Sisäisesti MCP-palvelin kääntää jokaisen työkalukutsun REST API -pyynnöksi. Se ei kopioi logiikkaa – se on tilaton silta.

Kehitys​

Osallistuaksesi tai ajaaksesi palvelinta kehitystilassa:

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

Suorita paikallisesti:

FRIHET_API_KEY=fri_tu_clave node dist/index.js

Suorita debug-lokien kanssa:

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

Testaa MCP Inspector -työkalulla:

npx @modelcontextprotocol/inspector node dist/index.js

Liittyvät resurssit​

Edellinen: Webhookit | Seuraava: Taito Claude Codelle