@ekwo-ai/mcp

The Model Context Protocol server for Ekwo OS. It lets an AI agent work on the books in your own Postgres: read the ledger, raise an invoice, post it, match a payment, pull the VAT return or the French FEC — as you, under the row level security of your own installation.

There are two ways to reach it, and they are the same server.

Hosted, at https://mcp.ekwo.ai/mcp

For a client that adds remote servers rather than launching them — claude.ai, or any other that speaks Streamable HTTP. Nothing is installed, and no password or key is written into a configuration file.

https://mcp.ekwo.ai/mcp

Point a client at that address and it discovers the rest. An unauthenticated call is answered with 401 and a WWW-Authenticate header naming the server's protected-resource metadata (RFC 9728); the client follows it to the authorization server (RFC 8414), registers itself (RFC 7591, so it needs no credentials of its own) and sends the person to their browser to approve the connection. The scope asked for is books.

An agent reading this without a browser can start from /.well-known/oauth-protected-resource.

The books stay where they are: the hosted server holds none, and connects to the instance the person names when they approve it.

Locally, over stdio

npx -y @ekwo-ai/mcp@latest

For a client that launches its own servers — Claude Desktop, Claude Code, any editor that reads .mcp.json. It speaks MCP over stdio and is started by a client, never by hand. Keep the version in the command: run from inside a clone of the Ekwo repository, a bare npx @ekwo-ai/mcp finds the workspace package of the same name, which has no built command, and answers ekwo-mcp: command not found. With @latest, npx fetches the published server wherever it is started. To run the server of the clone itself, build it (npm run build) and start node packages/mcp/dist/bin.js.

What it is, and what it is not

The server holds no privileges of its own. It signs in as the person using it, or is handed their access token, and everything it can do afterwards is exactly what that person can do: a viewer reads and cannot write, a member of one company cannot see another, a locked period refuses a posting. None of that is checked in this package — the policies and the triggers in the schema decide, and this server reports what they answered.

Three things it will never do:

• Write a ledger line. Every entry comes out of post_document, post_payment, post_entry or reconcile, which carry the accounting rules. Direct inserts are for the objects a person types: contacts, draft documents and their lines, payments, bank transactions.
• Delete or edit a posted entry. There is no unpost, and no tool that removes one. A mistake is corrected with a credit note, which is how accounting has always worked. unreconcile is the only undo here, and matching changes no account.
• Use a service_role key. It would work, and that is the objection: it bypasses every policy, so the agent would answer for companies its user was never invited to. The server refuses to start with one.

Configuration

The recommended route: PostgREST, as the signed-in user

{
  "mcpServers": {
    "ekwo": {
      "command": "npx",
      "args": ["-y", "@ekwo-ai/mcp@latest"],
      "env": {
        "SUPABASE_URL": "https://YOURREF.supabase.co",
        "SUPABASE_ANON_KEY": "your anon (publishable) key",
        "EKWO_EMAIL": "you@example.com",
        "EKWO_PASSWORD": "your password"
      }
    }
  }
}

That block goes in claude_desktop_config.json for Claude Desktop, or in .mcp.json at the root of a project for Claude Code. EKWO_ACCESS_TOKEN replaces the address and the password when you already hold a session; with the password, the session is kept in memory and refreshed, and nothing is written to disk.

The fallback: a direct Postgres connection

For a self-hosted installation with no PostgREST in front of the database, or for tests.

{
  "env": {
    "EKWO_DB_URL": "postgresql://…",
    "EKWO_ACT_AS_USER_ID": "the auth.users id this server acts for"
  }
}

EKWO_ACT_AS_USER_ID is required, and that is the whole point of this mode. A database connection is nobody: auth.uid() is null, row level security is bypassed rather than satisfied, and a server running that way would be a way round the policies rather than a client of them. So every query runs inside a transaction that sets request.jwt.claims to that user and switches to the authenticated role, and the policies bind exactly as they do over the API. This mode needs the postgres package installed alongside the server; the recommended route needs no driver at all.

Started with nothing set

A client lists a server's tools as soon as it is added, and so do the directories that index MCP servers. So with none of the variables above — or with half of them — the server still starts, still answers the list of tools, and every tool call returns a not_configured error that names the variables to set and where. It connects nowhere until then, and it offers the tools of the socle only: which modules an installation carries is read from its database.

Only absence is forgiven. A service_role key, in either slot, and an EKWO_ACT_AS_USER_ID that is not a uuid are values somebody wrote, and the server still refuses to start with them.

npm run build -w @ekwo-ai/mcp
node packages/mcp/scripts/introspect.mjs     # starts it with no environment and lists the tools

The Dockerfile at the root of the repository builds the same server from the checkout; docker run -i --rm <image> speaks MCP over stdio, with the variables passed as -e.

Over HTTP: hosting it for others

The same server, reached by URL instead of started by a client: handleHttpRequest answers the Streamable HTTP transport of MCP. It is stateless — each request builds a server, answers in JSON and closes it, with no session id and nothing kept — so it runs on a function platform, behind a load balancer, or in one process. A GET is answered 405: this server never speaks first, so there is no stream to open.

What it does not do is decide who is calling. That is the host's job, and the whole of it: the host authenticates the request its own way, then hands in the connection that request may use.

import { handleHttpRequest } from '@ekwo-ai/mcp';

export default async function (request: Request): Promise<Response> {
  const who = await yourOwnAuthentication(request);      // a token you issued
  if (who === undefined) return new Response(null, { status: 401 });
  return handleHttpRequest(request, {
    supabaseUrl: who.supabaseUrl,                         // https://<ref>.supabase.co
    anonKey: who.publishableKey,                          // never the service_role key
    apiKey: who.ekwoKey,                                  // or: accessToken: who.session
  });
}

A connection is one of two things, never both:

• A person's access token on the instance. Row level security decides, exactly as for that person in a browser.
• A key of Ekwo OS, as create_api_key() issues it. It travels in the X-Ekwo-Api-Key header with no Authorization beside it, the schema's pre-request hook presents it (decision 0062), and the caller is on that key's one company with that key's capabilities. A key issued without a capability that writes gives an agent that reads.

A service_role key is refused in all three slots, as on stdio. For node:http (or anything built on it), handleNodeRequest(req, res, connection, { origin }) is the same handler.

Putting it in front of people: authorization

A remote MCP client — Claude and the others — expects the server to follow the authorization part of the MCP specification: OAuth 2.1 with PKCE. That belongs to the host, not to this package, and a host that wants the clients to connect on their own serves:

1. 401 with WWW-Authenticate: Bearer resource_metadata="…" on the MCP endpoint when there is no valid token.
2. Protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource, naming the endpoint as the resource and the authorization server.
3. Authorization server metadata (RFC 8414) at /.well-known/oauth-authorization-server, with S256 in code_challenge_methods_supported.
4. Dynamic client registration (RFC 7591), or client metadata documents, so a client registers itself.
5. An authorization page where the person signs in the host's way and chooses what the client may reach; then a token endpoint that issues short access tokens and rotating refresh tokens.

Each access token the host issues maps to a connection — for instance to a key of Ekwo OS the person issued on their own installation for this purpose, held by the host encrypted and opened in memory for the one request. The database stays the only place that decides what may be read or written.

The tools

Every write names its company explicitly.

list_accounts answers with the working chart, not the whole one. A country pack transcribes the regulation — hundreds of accounts, and more than a thousand in the Luxembourg PCN or the SYSCOHADA — and a company works with a few dozen of them, so the default is what accounts_in_use() returns: the accounts carrying posted entries, those the company's own settings or an enabled module point at, and those somebody pinned, minus the deprecated ones. Every answer carries a scope field saying which it used. in_use_from and in_use_to narrow the movements to a period; include_all returns the whole chart; include_deprecated returns it with the retired accounts too; and ekwo://companies/{id}/chart was already the resource that carries everything. None of this restricts anything: a document line may name any account of the chart that is not deprecated, and every write tool still accepts one.

post_document, cancel_document, reverse_entry, record_payment, update_document_lines, unreconcile, lock_period, opening_balance, import_books, close_fiscal_year, reopen_fiscal_year, revoke_invitation, remove_member, set_member_role and revoke_api_key are annotated destructive in the protocol, so a client can ask before calling them.

What a tool may do is the capability the user holds, not the tool's own right: the server acts as the person it signed in as, so post_document works for an accountant and is refused to a viewer, by the database, with the database's own words. get_company returns your_capabilities for exactly that reason.

The modules. A module of this installation gets its own tools, under the prefix its module.json declares, and the server reads public.modules at startup to know which: fixed_assets_list, fixed_assets_create, fixed_assets_schedule, fixed_assets_run_depreciation, fixed_assets_dispose, budgets_list, budgets_upsert_lines, budgets_variance. The fixed assets tools were called assets_* until 0.10.0; those names are still registered, as deprecated aliases that say so in their description, and are removed in 0.11.0. A module that is not installed is not offered, because a tool a model cannot use is worse than a tool it cannot see. PostgREST serves a module's schema only once the project exposes it, and the refusal it answers with is a profile error that says nothing useful — so every module tool turns it into the sentence that names the setting.

Resources. ekwo://companies/{id}/chart is the whole chart of accounts; ekwo://companies/{id}/taxes is every tax with the ledger account and the declaration box each of its postings feeds.

Prompts. close_month walks the month-end checklist — drafts, unmatched bank lines, the balance, the VAT, what is still open. prepare_vat_return pulls the boxes and ties them back to the ledger before anything is filed.

Conventions

• Amounts are decimal strings. "1210.00", never a float. They go in that way and come back that way, because numeric is exact and a float is not.
• Dates are ISO, 2026-06-15. Identifiers are uuids.
• Totals are computed by the database. create_document returns the draft with the totals the schema derived, not with anything the caller supplied.
• Refusals travel unchanged. period_locked:, entry_unbalanced:, document_total_mismatch: and the rest arrive with the message the database raised, plus one sentence saying what it means. They are answers, not obstacles to route around.
• A product fills a line in and never constrains it. A line naming product_code takes the catalogue's text, description, unit, price, account and tax; anything the line carries wins over that. What is already posted is never touched when the catalogue changes, and a product referenced by a line is retired with active: false rather than deleted.
• A missing tax is a missing tax. A line with no tax books a base with no VAT box, which is not the same as 0 %. A missing account is different: it can only mean "resolve it", because a product line with no account is refused by a check constraint. So a line may leave account_code out, and the database fills it — the company default, then the country model.

Testing it by hand

The automated tests run every tool against the real schema in Postgres compiled to WebAssembly (tests/mcp/), including the refusals. Two things they cannot run: PostgREST and GoTrue. To exercise those, on a project you can throw away:

npx -y ekwo-os@latest init --country BE --org "Scratch" --company "Scratch BV" …   # a real project

Then point a client at it — in Claude Desktop, the JSON block above — and:

1. "List my companies." The company you created, with your_role: owner.
2. "What are the journals and the lock dates?" get_company.
3. "Create a customer called Dumont, then invoice them 1 000 € plus 21 % VAT for consulting." create_contact, then create_document; the answer carries amount_total: "1210.00" computed by the database. Or with a catalogue: "add a product CONS-JOUR, a consulting day at 500 € on 704000 at 21 %, then invoice Dumont two of them" — create_product, then create_document with product_code and nothing else on the line.
4. "Post it." post_document. The entry books 704 / 451 / 400 and takes a number like SAL/2026/0001.
5. "They paid 500 € on the 10th." record_payment, which books the bank line and matches it; the invoice becomes partially paid.
6. "Show me the trial balance and the VAT for the quarter." trial_balance and vat_return.
7. "Lock June." lock_period, then try to post something dated in June: the refusal comes back as period_locked:.

A payment needs somewhere to book the bank side. On a company installed from a country model the bank and cash journals already point at their account (550000 and 570000 in Belgium, 512000 and 530000 in France), so record_payment works with nothing else set up. create_bank_account names the real account — its identifier is the one thing nobody can derive — and wires it to the journal; bank_account_id on the payment then says which one the money moved on, which is what you need with several accounts in one journal. Until a company has one, ekwo doctor says so.

Licence

AGPL-3.0-only © Ekwo AI.