Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase…

@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, prepare the VAT return — 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 chooses when they approve it. On the same screen they decide whether the agent may write; otherwise it reads. The hosted server is operated by Ekwo Cloud, and signing in there needs an account — a free one, opened with an address and a six-digit code, which also gives the web application on the same books and a nightly backup of every company it links.

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 — against any installation, with no account. Keep @latest in the command: from inside a clone of the repository, a bare npx @ekwo-ai/mcp finds the unbuilt workspace package and answers ekwo-mcp: command not found.

With the command line installed, ekwo mcp starts the same server — the same entry point, runStdio(), the same flags (--autopilot, --review) and the same environment: "command": "ekwo", "args": ["mcp"].

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 the schema's own functions, 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. No tool removes one. A posted invoice is undone the one way its country allows — back to draft where nothing about it has left, otherwise by the credit note that names it — and an entry keyed by hand by its reversal.
• 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 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.

It does not decide who is calling: 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 { 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:// .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 expects the server to follow the authorization part of the MCP specification: OAuth 2.1 with PKCE, protected resource metadata (RFC 9728), authorization server metadata (RFC 8414) and dynamic client registration (RFC 7591). That belongs to the host, not to this package: the host signs the person in, issues its own tokens, and maps each one to a connection above. The database stays the only place that decides what may be read or written.

The tools

Every write names its company explicitly.

| render_invoice_pdf | The PDF of a sale invoice or credit note, as a PDF resource (base64) b