MCP server

The Feeef MCP server exposes the whole commerce platform as Model Context Protocol tools, so AI agents — Cursor, Claude Code, Claude Desktop, VS Code Copilot, or your own agent — can manage stores, products, orders (including Ecotrack delivery), landing pages, inventory, finance and more on a merchant's behalf. It is a thin, stateless-by-design bridge: every tool call becomes a REST API request authenticated with the connected user's bearer token.

How it fits together

Two ways to authenticate

1. MCP OAuth (recommended for IDE hosts)

Clients that implement the MCP authorization spec need zero configuration beyond the URL. An unauthenticated initialize receives 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp; the host then discovers the authorization server metadata and runs a standard authorization-code + PKCE flow (PKCE is mandatory):

1. The host opens GET /authorize in the browser, which redirects to the Feeef sign-in on accounts.feeef.org.
2. After consent, Feeef calls the server's registered callback (/oauth/feeef/callback), which redirects back to the host's redirect_uri with an authorization code.
3. The host exchanges the code (plus PKCE verifier) at POST /token and receives the Feeef bearer token as access_token.

Loopback and IDE custom-scheme redirect URIs (cursor://, vscode://, …) are accepted out of the box per RFC 8252. Other public HTTPS redirect URIs must first be registered through the open dynamic client registration endpoint POST /register (RFC 7591). The bridge flow itself is the same authorization-code flow used across the platform.

2. Direct bearer token

Clients that support custom headers can skip OAuth entirely and send a Feeef API token on initialize:

Authorization: Bearer oat_...
Accept: application/json, text/event-stream
Content-Type: application/json

The token is bound to the MCP session and reused for every tool call in it. Any valid API token works: a first-party sign-in token or an OAuth app token with limited scopes.

Scopes and permissions

The MCP server does not run its own permission system — enforcement happens upstream at the Feeef API, exactly as if the agent called the REST API directly:

• Token scopes. Tool calls carry the session's bearer token, so what the agent can do is what that token's scopes allow. A bearer token minted for products.read fails on products_update with a permission error. Note that the hosted OAuth bridge requests the full * scope on the consent screen — connect with a scoped token via the bearer header when you want a narrower blast radius.
• Store roles. Store-member RBAC still applies: a viewer member cannot mutate orders no matter which token they hold.
• Integration gates. finance_* and inventory_* tools require the corresponding paid integration to be active on the store. When it is not, the tool returns a structured integration_required payload naming integrations_subscribe as the fix, instead of a hard error.

The server://scope MCP resource returns the live tool surface as one JSON map of namespaces to qualified tool names. It is generated at runtime from the registration catalog, so it can never drift from what is actually registered:

{
  "namespaces": {
    "auth": ["auth_me", "auth_update"],
    "stores": ["stores_list", "stores_get", "..."],
    "orders": ["orders_list", "orders_send_to_ecotrack", "..."]
  }
}

server://info is a small JSON resource describing the server (name, transport, auth mode).

Sessions

Each initialize creates a server-side session identified by the mcp-session-id header, with the bearer token bound to it. Sessions idle for more than 12 hours are evicted; an expired session answers 404, and spec-compliant clients re-initialize transparently.

Self-hosting

The server is a plain dart:io binary (no web framework) shipped as a from-scratch Docker image. The build AOT-compiles bin/server.dart and copies docs/ into the image — the docs_* and tool_doc_* tools read those markdown files at runtime.

docker build -t feeef-mcp .

docker run -p 8080:8080 \
  -e FEEEF_CLIENT_ID=... \
  -e FEEEF_CLIENT_SECRET=... \
  -e FEEEF_BASE_URL=https://api.feeef.org/v1 \
  feeef-mcp

The client id/secret identify the developer OAuth app the bridge signs users in with — register one in the dashboard and allowlist your callback URL (exact match) against it. The server exits at startup if no client id/secret is available.

The callback URL resolves in priority order: FEEEF_OAUTH_REDIRECT_URI, then FEEEF_MCP_PUBLIC_ORIGIN + /oauth/feeef/callback, then the loopback URL when FEEEF_MCP_DEV=1, else the production default https://mcp.feeef.org/oauth/feeef/callback. Verify a running instance with GET /health — it reports the active upstream as feeefBaseUrl, plus session count and OAuth endpoints.