MCP Config Tools (flapi_*)

In addition to the data tools you define yourself in YAML, flAPI ships a built-in family of admin tools that let an AI agent introspect and reconfigure the running flAPI server itself. These are exposed via the same MCP transport (POST /mcp/jsonrpc) and prefixed with flapi_.

They unlock workflows like:

• "Show me the schema of the customer database, then create a GET /customers endpoint backed by customers.sql."
• "Validate the Mustache template for the orders endpoint and hot-reload it."
• "Refresh the cache for dashboard_metrics and show me the audit trail."

Data Tools vs. Config Tools

	Data tools	Config tools
Defined where	mcp-tool: blocks in your endpoint YAML	Built into the flAPI binary
Name pattern	Anything you choose (e.g. get_orders)	flapi_*
What they do	Execute SQL against your data	Manage endpoints, templates, caches
Always available?	Yes (whenever the endpoint is configured)	Only with --config-service
Authentication	Endpoint-level auth	Config service token (Bearer) for mutating tools

Both kinds of tools appear in the same tools/list response and are invoked the same way via tools/call.

Enabling Config Tools

The flapi_* tools are gated behind the Config Service feature, which must be enabled at startup:

# Enable config service (and config tools) with no auth
./flapi --config-service

# Recommended: also set an admin token
./flapi --config-service --config-service-token "your-secret-token"

Without --config-service, flAPI's ConfigToolAdapter is not constructed, and any flapi_* call returns -32603 Tool execution failed: Config tools not available.

See also: Configuration Service (REST counterpart and CLI).

Authentication

The config tools share their authentication model with the REST Config Service:

• Read tools (flapi_get_*, flapi_list_*, flapi_expand_*, flapi_test_*) are unauthenticated by default.
• Mutating tools (flapi_create_*, flapi_update_*, flapi_delete_*, flapi_reload_*, flapi_refresh_*, flapi_run_*) require a valid token when one was set at startup with --config-service-token.

Pass the token as a Bearer header on each MCP request:

Authorization: Bearer your-secret-token

flAPI extracts the token in MCPRouteHandlers::handleToolsCallRequest and threads it to ConfigToolAdapter::executeTool.

Tool Catalog

There are 19 flapi_* tools, organised into four functional categories. (The upstream reference document is internally inconsistent—the header claims 20 and another section says 18—but counting the ### flapi_* entries in MCP_CONFIG_TOOLS_API.md yields 19. Sources: src/mcp_route_handlers.cpp, docs/MCP_CONFIG_TOOLS_API.md.)

Discovery (5 tools, read-only)

Introspect the project, environment, filesystem, and database schema.

Tool	Args	Purpose
flapi_get_project_config	—	Project metadata: name, description, base path, version
flapi_get_environment	—	Whitelisted environment variables visible to templates
flapi_get_filesystem	—	Tree of YAML/SQL files under the project root
flapi_get_schema	—	Aggregate schema (tables/columns) for all connections
flapi_refresh_schema	—	Force a re-discovery of all connection schemas

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "flapi_get_schema", "arguments": {} }
}

Template (4 tools)

Read, write, expand, and validate SQL templates.

Tool	Args	Auth	Purpose
flapi_get_template	endpoint	—	Read the raw SQL template content
flapi_update_template	endpoint, content	Yes	Overwrite the template file on disk
flapi_expand_template	endpoint, params?	—	Render Mustache with sample params (no SQL execution)
flapi_test_template	endpoint	—	Validate Mustache/template syntax

Example — preview how a template renders before saving:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "flapi_expand_template",
    "arguments": {
      "endpoint": "customers",
      "params": { "id": "42" }
    }
  }
}

Endpoint (6 tools)

CRUD plus hot-reload for REST/MCP endpoint configuration.

Tool	Args	Auth	Purpose
flapi_list_endpoints	—	—	List all configured endpoints with type (rest/mcp)
flapi_get_endpoint	path	—	Full configuration for one endpoint
flapi_create_endpoint	path, method?, template_source?	Yes	Create a new endpoint YAML
flapi_update_endpoint	path, method?, template_source?	Yes	Modify an existing endpoint
flapi_delete_endpoint	path	Yes	Remove an endpoint
flapi_reload_endpoint	path	Yes	Re-read the endpoint YAML from disk without restarting flAPI

Example — let an agent create a new endpoint end-to-end:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "flapi_create_endpoint",
    "arguments": {
      "path": "customers",
      "method": "GET",
      "template_source": "customers.sql"
    }
  }
}

Cache (4 tools)

Inspect and operate flAPI's DuckLake-backed endpoint cache.

Tool	Args	Auth	Purpose
flapi_get_cache_status	path	—	Is caching enabled? Which DuckLake table?
flapi_refresh_cache	path	Yes	Trigger a manual cache refresh for one endpoint
flapi_get_cache_audit	path	—	Recent cache events (refreshes, status checks)
flapi_run_cache_gc	path?	Yes	Run garbage collection (per-endpoint or globally)

Example — refresh a cache from an agent:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "flapi_refresh_cache",
    "arguments": { "path": "dashboard_metrics" }
  }
}

Worked Example: "Add an endpoint by chat"

Here is the typical sequence an AI coding assistant runs when asked to create a new endpoint. All calls go to POST /mcp/jsonrpc; only the JSON body is shown.

// 1. Inspect the database
{ "method": "tools/call",
  "params": { "name": "flapi_get_schema", "arguments": {} } }

// 2. See what already exists
{ "method": "tools/call",
  "params": { "name": "flapi_list_endpoints", "arguments": {} } }

// 3. Create the endpoint
{ "method": "tools/call",
  "params": {
    "name": "flapi_create_endpoint",
    "arguments": {
      "path": "customers",
      "method": "GET",
      "template_source": "customers.sql"
    }
  } }

// 4. Write the SQL template
{ "method": "tools/call",
  "params": {
    "name": "flapi_update_template",
    "arguments": {
      "endpoint": "customers",
      "content": "SELECT id, name, email FROM customers WHERE 1=1 {{#params.id}}AND id = {{{params.id}}}{{/params.id}}"
    }
  } }

// 5. Validate it
{ "method": "tools/call",
  "params": { "name": "flapi_test_template", "arguments": { "endpoint": "customers" } } }

// 6. Hot-reload it into the running server
{ "method": "tools/call",
  "params": { "name": "flapi_reload_endpoint", "arguments": { "path": "customers" } } }

// 7. Verify it
{ "method": "tools/call",
  "params": { "name": "flapi_get_endpoint", "arguments": { "path": "customers" } } }

After step 6 the endpoint is live—GET /customers works immediately without restarting flAPI.

Error Responses

Config tools return structured errors as a JSON-encoded string inside the standard -32603 JSON-RPC error message. Always parse the message body for actionable detail:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Tool execution failed: {\"error\":\"Endpoint not found\",\"path\":\"nonexistent\",\"hint\":\"Use flapi_list_endpoints to see available endpoints\"}"
  }
}

The inner JSON typically includes:

• error — short description
• path / endpoint / template — which resource failed
• reason — underlying exception (when applicable)
• hint — actionable next step for the agent

Best Practices

1. List before mutate. Always call flapi_list_endpoints or flapi_get_endpoint before flapi_update_* / flapi_delete_*.
2. Validate templates first. Call flapi_test_template and flapi_expand_template before flapi_update_template.
3. Reload after writes. Use flapi_reload_endpoint to apply YAML changes without a server restart.
4. Audit cache changes. Use flapi_get_cache_audit to confirm refreshes landed.
5. Bearer tokens, not secrets in prompts. Pass the config-service token via the bridge's Authorization header, not as plaintext arguments.

See Also

• MCP Overview — what data tools look like
• MCP Protocol Reference — wire-level JSON-RPC details
• Claude Integration — wiring an agent
• Configuration Service — the REST API and CLI counterparts of these tools
• Upstream source of truth: docs/MCP_CONFIG_TOOLS_API.md in the flAPI repository