MCP Configuration Tools API Reference

Complete reference for all 20 MCP configuration management tools in flAPI. These tools enable AI agents to programmatically manage REST API endpoints, SQL templates, and cache configurations at runtime.

Overview

The Configuration Service exposes 20 MCP tools organized into 4 functional categories:

Discovery Tools (5): Read-only introspection of project configuration
Template Tools (4): SQL template management and testing
Endpoint Tools (6): CRUD operations for REST endpoints
Cache Tools (4): Cache status and management operations

All tools use JSON-RPC 2.0 protocol with MCP error codes for standardized error handling.

Activation Requirement

⚠️ Important: The MCP configuration tools (flapi_*) are only available when the server is started with the --config-service flag. Without this flag, only declarative MCP tools from YAML configurations are accessible.

To enable config MCP tools:

./flapi --config-service
./flapi --config-service --config-service-token "your-token"  # With authentication

When --config-service is NOT enabled:

Config tools (flapi_get_*, flapi_create_*, etc.) will return "Tool not found" errors
Only endpoint-based MCP tools from your YAML configurations are available
REST configuration API (/api/v1/_config/*) is also disabled

Error Codes: See MCP Reference § Appendix B for complete MCP error reference.

Authentication: See Configuration Reference § 7 for all authentication schemes and setup.

Discovery Tools

Read-only tools for introspecting project configuration and database schema.

flapi_get_project_config

Get project metadata and configuration information.

Authentication: Not required

Parameters: None

Response (Success):

{
  "project_name": "my-api-project",
  "project_description": "REST API for customer data",
  "base_path": "/home/user/projects/my-api",
  "version": "1.0.0"
}

Error Response:

{
  "error": "Configuration service unavailable"
}

flapi_get_environment

Get whitelisted environment variables available to templates.

Authentication: Not required

Parameters: None

Response (Success):

{
  "variables": [
    {
      "name": "DB_HOST",
      "value": "localhost"
    },
    {
      "name": "DB_PORT",
      "value": "5432"
    }
  ]
}

flapi_get_filesystem

Get directory structure of template and configuration files.

Authentication: Not required

Parameters: None

Response (Success):

{
  "base_path": "/home/user/projects/my-api",
  "template_path": "/home/user/projects/my-api/sqls",
  "tree": [
    {
      "name": "customers.sql",
      "type": "file",
      "size": 1024
    },
    {
      "name": "orders.sql",
      "type": "file",
      "size": 2048
    }
  ]
}

flapi_get_schema

Get database schema information for all configured connections.

Authentication: Not required

Parameters: None

Response (Success):

{
  "tables": [
    {
      "name": "customers",
      "schema": "public",
      "columns": [
        {
          "name": "id",
          "type": "INTEGER",
          "nullable": false
        },
        {
          "name": "name",
          "type": "VARCHAR",
          "nullable": false
        }
      ]
    }
  ]
}

flapi_refresh_schema

Refresh database schema cache by querying all connections.

Authentication: Not required

Parameters: None

Response (Success):

{
  "status": "schema_refreshed",
  "timestamp": "1704067200",
  "message": "Database schema cache has been refreshed"
}

Template Tools

Tools for managing and testing SQL templates with Mustache syntax.

flapi_get_template

Retrieve the SQL template content for an endpoint.

Authentication: Not required

Parameters:

endpoint (string, required): Endpoint identifier or filename (e.g., "customers")

Response (Success):

{
  "endpoint": "customers",
  "content": "SELECT * FROM customers\nWHERE 1=1\n{{#params.id}}\n  AND id = {{{ params.id }}}\n{{/params.id}}",
  "message": "Template retrieved"
}

Error Response (Endpoint not found):

{
  "error": "Endpoint not found",
  "endpoint": "customers",
  "hint": "Use flapi_list_endpoints to see available endpoints or flapi_create_endpoint to create new one"
}

flapi_update_template

Update the SQL template content for an endpoint (requires authentication).

Authentication: Required

Parameters:

endpoint (string, required): Endpoint identifier
content (string, required): New template SQL content with Mustache syntax

Response (Success):

{
  "endpoint": "customers",
  "message": "Template updated successfully",
  "content_length": 256
}

Error Response (Endpoint not found):

{
  "error": "Endpoint not found",
  "endpoint": "customers",
  "hint": "Use flapi_list_endpoints to see available endpoints"
}

flapi_expand_template

Test Mustache template expansion with sample parameters.

Authentication: Not required

Parameters:

endpoint (string, required): Endpoint identifier
params (object, optional): Sample parameters for template expansion

Response (Success):

{
  "endpoint": "customers",
  "expanded_sql": "SELECT * FROM customers\nWHERE 1=1\n  AND id = 123",
  "status": "Template expanded successfully"
}

flapi_test_template

Validate template syntax and Mustache syntax.

Authentication: Not required

Parameters:

endpoint (string, required): Endpoint identifier

Response (Success):

{
  "endpoint": "customers",
  "valid": true,
  "message": "Template syntax is valid"
}

Error Response (Invalid syntax):

{
  "error": "Template syntax error",
  "endpoint": "customers",
  "reason": "Unclosed Mustache block at line 3"
}

Endpoint Tools

CRUD operations for REST endpoint configuration (path, method, template, cache).

flapi_list_endpoints

List all configured REST and MCP endpoints.

Authentication: Not required

Parameters: None

Response (Success):

{
  "count": 2,
  "endpoints": [
    {
      "name": "GetCustomers",
      "path": "customers",
      "method": "GET",
      "type": "rest"
    },
    {
      "name": "ListOrders",
      "path": "orders",
      "method": "GET",
      "type": "rest"
    }
  ]
}

flapi_get_endpoint

Get complete configuration for a specific endpoint.

Authentication: Not required

Parameters:

path (string, required): Endpoint path

Response (Success):

{
  "name": "GetCustomers",
  "path": "customers",
  "method": "GET",
  "template_source": "customers.sql",
  "connections": ["db-primary"],
  "auth_required": false,
  "cache_enabled": true
}

Error Response (Endpoint not found):

{
  "error": "Endpoint not found",
  "path": "customers",
  "hint": "Use flapi_list_endpoints to see available endpoints"
}

flapi_create_endpoint

Create a new REST endpoint (requires authentication).

Authentication: Required

Parameters:

path (string, required): Endpoint URL path (e.g., "customers")
method (string, optional): HTTP method - GET, POST, PUT, DELETE (defaults to GET)
template_source (string, optional): SQL template filename

Response (Success):

{
  "status": "success",
  "path": "customers",
  "method": "GET",
  "template_source": "customers.sql",
  "message": "Endpoint created successfully"
}

Error Response (Endpoint exists):

{
  "error": "Endpoint already exists",
  "path": "customers",
  "hint": "Use flapi_update_endpoint to modify existing endpoint, or delete it first with flapi_delete_endpoint"
}

flapi_update_endpoint

Modify an existing endpoint configuration (requires authentication).

Authentication: Required

Parameters:

path (string, required): Endpoint path to update
method (string, optional): New HTTP method
template_source (string, optional): New template filename

Response (Success):

{
  "status": "success",
  "path": "customers",
  "message": "Endpoint updated successfully",
  "previous_method": "GET",
  "new_method": "POST",
  "previous_template": "customers.sql",
  "new_template": "customers_create.sql"
}

flapi_delete_endpoint

Remove an endpoint from configuration (requires authentication).

Authentication: Required

Parameters:

path (string, required): Endpoint path to delete

Response (Success):

{
  "status": "success",
  "path": "customers",
  "message": "Endpoint deleted successfully",
  "deleted_method": "GET",
  "deleted_template": "customers.sql"
}

flapi_reload_endpoint

Hot-reload endpoint configuration from disk without restarting server (requires authentication).

Authentication: Required

Parameters:

path (string, required): Endpoint path to reload

Response (Success):

{
  "status": "success",
  "path": "customers",
  "message": "Endpoint configuration reloaded from disk",
  "original_method": "GET",
  "original_template": "customers.sql"
}

Error Response (Load fails):

{
  "error": "Failed to reload endpoint configuration from disk",
  "path": "customers",
  "hint": "Verify that endpoint YAML file exists and is valid"
}

Cache Tools

Monitor and manage DuckLake cache for endpoints.

flapi_get_cache_status

Get cache status and configuration for an endpoint.

Authentication: Not required

Parameters:

path (string, required): Endpoint path

Response (Success):

{
  "status": "success",
  "path": "customers",
  "cache_enabled": true,
  "cache_table": "customers_cache",
  "cache_schema": "cache_v1"
}

Error Response (Cache not enabled):

{
  "error": "Cache not enabled for this endpoint",
  "path": "customers",
  "method": "GET",
  "hint": "Enable cache in endpoint YAML configuration and reload endpoint"
}

flapi_refresh_cache

Trigger manual cache refresh for an endpoint (requires authentication).

Authentication: Required

Parameters:

path (string, required): Endpoint path

Response (Success):

{
  "path": "customers",
  "status": "Cache refresh triggered",
  "cache_table": "customers_cache",
  "timestamp": "1704067200",
  "message": "Cache refresh has been scheduled"
}

flapi_get_cache_audit

Get audit log of cache operations and refresh history.

Authentication: Not required

Parameters:

path (string, required): Endpoint path

Response (Success):

{
  "path": "customers",
  "cache_table": "customers_cache",
  "audit_log": [
    {
      "timestamp": "1704067200",
      "event": "cache_refreshed",
      "status": "success"
    },
    {
      "timestamp": "1704063600",
      "event": "cache_status_checked",
      "status": "success"
    }
  ],
  "message": "Cache audit log retrieved successfully"
}

flapi_run_cache_gc

Trigger garbage collection to clean up old cache snapshots (requires authentication).

Authentication: Required

Parameters:

path (string, optional): Endpoint path for targeted GC (if omitted, runs globally)

Response (Success - Endpoint-specific):

{
  "status": "Garbage collection triggered",
  "path": "customers",
  "timestamp": "1704067200",
  "message": "Cache garbage collection for endpoint scheduled"
}

Response (Success - Global):

{
  "status": "Garbage collection triggered",
  "scope": "all_caches",
  "timestamp": "1704067200",
  "message": "Global cache garbage collection has been scheduled"
}

Error Handling Guidelines

Structured Error Responses

All errors include:

error: Description of what failed
path/method/template: Resource details
reason: Underlying exception (if applicable)
hint: Actionable guidance for resolution

Example Error Flow

Request:

{
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "name": "flapi_get_endpoint",
    "arguments": {
      "path": "nonexistent"
    }
  }
}

Response (Error):

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

Rate Limiting

Configuration tools do not have built-in rate limiting but respect server-level rate limits.

Concurrency Considerations

Read operations (list, get, read) are safe for concurrent access
Write operations (create, update, delete, reload) lock the endpoint configuration
Cache operations are atomic with respect to the cache table
Multiple concurrent writes to the same endpoint may see conflicts

Best Practices

Always list endpoints first: Use flapi_list_endpoints to verify endpoint exists before operating on it
Validate templates before updating: Use flapi_test_template to validate syntax before flapi_update_template
Check cache status before refresh: Use flapi_get_cache_status to verify cache is enabled before refreshing
Handle structured errors: Parse error responses for hint field to guide users
Authenticate with correct scheme: Use Bearer for JWT tokens, Basic for credentials, Token for API keys
Reload after configuration changes: Use flapi_reload_endpoint to apply changes without server restart

Common Workflows

Create a New Endpoint

Call flapi_list_endpoints to see existing endpoints
Call flapi_create_endpoint with path, method, template_source
Call flapi_get_endpoint to verify creation
Call flapi_test_template to validate template

Update Endpoint Configuration

Call flapi_get_endpoint to see current config
Call flapi_update_endpoint with new values
Call flapi_reload_endpoint to apply changes
Verify with flapi_get_endpoint

Manage Cache

Call flapi_get_cache_status to check if cache is enabled
Call flapi_refresh_cache to manually refresh if needed
Call flapi_get_cache_audit to review refresh history
Call flapi_run_cache_gc periodically to clean up snapshots

API Version

These tools implement MCP Configuration Service v1.0 for flAPI.

For integration guidance, see MCP Configuration Integration Guide.

FilesExpand file tree

MCP_CONFIG_TOOLS_API.md

Latest commit

History

MCP_CONFIG_TOOLS_API.md

File metadata and controls

MCP Configuration Tools API Reference

Overview

Activation Requirement

Discovery Tools

flapi_get_project_config

flapi_get_environment

flapi_get_filesystem

flapi_get_schema

flapi_refresh_schema

Template Tools

flapi_get_template

flapi_update_template

flapi_expand_template

flapi_test_template

Endpoint Tools

flapi_list_endpoints

flapi_get_endpoint

flapi_create_endpoint

flapi_update_endpoint

flapi_delete_endpoint

flapi_reload_endpoint

Cache Tools

flapi_get_cache_status

flapi_refresh_cache

flapi_get_cache_audit

flapi_run_cache_gc

Error Handling Guidelines

Structured Error Responses

Example Error Flow

Rate Limiting

Concurrency Considerations

Best Practices

Common Workflows

Create a New Endpoint

Update Endpoint Configuration

Manage Cache

API Version

Related Documentation