flAPI ships a Claude Code plugin. With it installed, Claude knows how to set up a flAPI project, write REST endpoints and MCP tools, design and tune DuckLake caches, secure, test, deploy and operate a server. It checks its own edits against your config, and it can manage a running server through flAPI's MCP config tools.
In Claude Code:
/plugin marketplace add DataZooDE/flapi
/plugin install flapi@flapi
The plugin needs the flapi server binary for validation and the flapii CLI for
a running server. pip install flapi-io installs both.
To update it, run /plugin marketplace update flapi. The plugin version follows
flAPI's release version, so use the plugin release that matches your server.
Claude loads a skill when your request matches it. You do not have to invoke one.
| Phase | Skill | Covers |
|---|---|---|
| Setup | flapi-setup |
Installing, flapii project init, flapi.yaml, connections, environment-variable whitelist, DuckDB extensions, validation |
| Develop | flapi-rest |
Endpoint YAML, parameters and validators, Mustache SQL templates, pagination, write endpoints, YAML includes, rate limits |
| Develop | flapi-mcp |
MCP tools, resources and prompts, descriptions an agent can act on, async tasks, one endpoint for REST and MCP, connecting clients |
| Develop | flapi-auth |
Basic, bearer JWT, OIDC with provider presets, roles, MCP OAuth, the config-service token, CORS |
| Develop | flapi-cache-design |
Full, append and merge caches, writing the populate SQL, cursors and watermarks, deletes, warm-up, write-through, replicas, prebuilt caches, time travel |
| Develop | flapi-cache-tuning |
Measuring refresh time and cutting it down: predicate pushdown, incremental loads, schedules, inlining, compaction, retention |
| Develop | flapi-testing |
Template expansion, --validate-config, Tavern REST tests, MCP tests, CI |
| Develop | flapi-live-config |
The config service, flapii, the flapi_* MCP config tools, hot reload |
| Deploy | flapi-deploy |
flapi pack single binaries, Docker, Cloud Run / serverless, secrets, offline extensions |
| Operate | flapi-operate |
Health and readiness, runtime metrics, logs, tracing, cache operations, troubleshooting |
| Command | Does |
|---|---|
/flapi:init |
Scaffolds a project from a description of your data, then validates and starts it |
/flapi:new-endpoint |
Creates the YAML, SQL, validators, an optional MCP tool and a test, then tries them |
/flapi:add-cache |
Picks a cache mode, writes the populate SQL, refreshes, measures and tunes |
/flapi:auth-setup |
Configures authentication and roles, and proves the 401/403/200 paths with curl |
/flapi:deploy-check |
Runs a pre-deployment checklist and builds the artifact |
/flapi:diagnose |
Goes from an error to a root cause and a verified fix |
/flapi:metrics |
Summarizes slow or failing endpoints, rejections and slow or stale caches |
The plugin registers a flapi MCP server at $FLAPI_URL/mcp/jsonrpc (default
http://localhost:8080). It sends two headers:
X-Config-Token: $FLAPI_CONFIG_SERVICE_TOKEN, for theflapi_*config tools;Authorization: Bearer $FLAPI_MCP_TOKEN, formcp.auth(a JWT the server'smcp.authaccepts). WithFLAPI_MCP_TOKENunset the header is an emptyBearer, which a server withoutmcp.authignores and a server with it answers 401Authentication required for method: ....
Both variables default to empty (${VAR:-} in .mcp.json), so the server
registers even when neither is set. The config token used to go in
Authorization, so once mcp.auth was on every plugin call was a 401.
To point the plugin at a server with mcp.auth on, export FLAPI_MCP_TOKEN:
for mcp.auth.type: bearer an HS256 JWT signed with jwt-secret, with sub, an
iss equal to jwt-issuer and a roles claim that matches the tools'
allowed-roles; for type: oidc an access token from the identity provider. A
server with type: basic needs an Authorization: Basic ... header, which the
plugin entry cannot send: register it yourself with claude mcp add --transport http ... --header "Authorization: Basic <base64 user:pass>" --header "X-Config-Token: $FLAPI_CONFIG_SERVICE_TOKEN".
Claude then sees your endpoints as MCP tools. If the server runs with
--config-service, Claude also sees the flapi_* config tools. With those it can
list and edit endpoints, expand templates, refresh caches and read
flapi_get_metrics. The flapi_* tools are listed in tools/list even without
the token, but every call needs the config-service token, which X-Config-Token
carries (without it: JSON-RPC -32001 Authentication required for tool: ...). Endpoint changes show up in tools/list at once,
without a restart.
export FLAPI_CONFIG_SERVICE_TOKEN=$(openssl rand -hex 32)
export FLAPI_MCP_TOKEN=... # only when mcp.auth is enabled
flapi -c flapi.yaml --config-service --config-service-token "$FLAPI_CONFIG_SERVICE_TOKEN"
# then start Claude Code in the same shellAfter Claude edits a .yaml, .yml or .sql file inside a flAPI project (a
directory with a flapi.yaml in it or above it, or inside the template.path of
the config FLAPI_CONFIG names, e.g. a ../sqls shared by a writer and a
replica), the plugin:
- runs
flapi -c <flapi.yaml> --validate-config, ifflapiis onPATHorFLAPI_BINis set. Any errors go back to Claude, which fixes them. - reloads the edited endpoint file on the running server, if validation passed
and
FLAPI_CONFIG_SERVICE_TOKENis set (POST /api/v1/_config/endpoints/reload-fileonFLAPI_URL; a new file is loaded too). For a.sqlfile, every endpoint YAML that uses it astemplate-sourceor cachetemplate-fileis reloaded. A file that no longer loads is rejected with its reason, and the endpoint keeps its previous configuration. - checks the affected templates without running them
(
template/expand?validate_only=1, see the API reference): the serving template once with no parameters and once with a sample value for every typed request field (int-> itsminor 1,string-> a value matching its regex,enum-> the first value,date-> today, ...), so SQL inside{{#params.x}}sections is checked as well; a cachetemplate-filewithtarget=cache&validate_only=1, i.e. with the live watermark, per statement, with the bare-SELECT rule. Parse and bind errors (an unknown column,MERGE INTOO) go back to Claude. The message names the parameter sets it checked. A parameter used insideAT (VERSION => ...)/AT (TIMESTAMP => ...)gets no sample value: an invented snapshot does not exist. A cached endpoint whose cache table does not exist yet (seen on the no-parameter run) is a note ("cache not built yet; runflapii cache refresh <path>"), not an error; a failing sample run is always reported as the error it is. A validation that had to drop the cache's watermark says so: the next refresh would load the full source.
The hook first checks that the server at FLAPI_URL is this project's, and
only then sends the token: GET /doc.yaml (no token) must name this
flapi.yaml's project-name, and then template.path must be this project's
directory. Otherwise it says which URL it found and sends nothing there. It
does not reload into a server that cannot take the edit either: a server
running from a packed bundle (flapi pack; edits on disk cannot reach it), or
one started before flapi.yaml changed when the ducklake, auth or mcp
settings it reports differ from the file ("restart the server first").
After a shell command that deletes an endpoint YAML in template.path (rm,
git rm, unlink, mv elsewhere), or an edit whose file no longer exists, the
hook passes the file to reload-file, which unloads what it declared
(200 {"status":"removed","removed":[...]}), and reports the removed endpoints.
A 404 means nothing was loaded from that file (a server too old to unload
deleted files answers 404 as well and keeps serving them until it restarts).
If something is missing (no binary, no project, no token, no server), the hook does nothing. It never blocks an edit.
| Variable | Default | Used by |
|---|---|---|
FLAPI_URL |
http://localhost:8080 |
MCP server, hook, flapii (when FLAPI_BASE_URL is unset) |
FLAPI_CONFIG_SERVICE_TOKEN |
— | MCP server (X-Config-Token), hook, flapii |
FLAPI_MCP_TOKEN |
— | MCP server (Authorization: Bearer, for mcp.auth) |
FLAPI_BIN |
flapi on PATH |
hook |
FLAPI_CONFIG |
nearest flapi.yaml |
hook (also for files under its template.path) |
The plugin lives in this repository under plugins/flapi/.
To try local changes without installing:
claude --plugin-dir ./plugins/flapimake check-skills checks every skill against the real code and binaries:
- configuration keys against the parser
flapi/flapiicommands and options against--help- cache template variables
- the version stamp
- every tagged example, which it runs through
flapi --validate-configand a live server
CI runs the same check. Update a skill in the same pull request as the feature it describes.