Florentine MCP Server

How to use

You connect your own MCP client to the Florentine MCP Server and use the florentine_ask tool to translate user questions into aggregations. The server can return the generated pipeline, the raw results, and/or a natural language answer depending on the configured return types. You can operate in static mode when using existing external MCP clients or in dynamic mode when you want to inject parameters per request from your own client.

How to install

Prerequisites: Node.js >= v18.0.0, a Florentine.ai account, a connected database with at least one analyzed collection, and a Florentine.ai API Key.

Install and run the MCP Server using npx with a static setup as shown in this example.

{
  "mcpServers": {
    "florentine": {
      "command": "npx",
      "args": ["-y", "@florentine-ai/mcp", "--mode", "static"],
      "env": {
        "FLORENTINE_TOKEN": "<FLORENTINE_API_KEY>"
      }
    }
  }
}

Static vs Dynamic modes

Static mode is used when integrating Florentine AI into existing MCP clients. All parameters (return types, required inputs, etc.) are defined in the config and sent with every request. Dynamic mode is used when you implement a custom MCP client and want to provide or override parameters per request.

Static mode example shows environment-based configuration including session, LLM settings, and return types. Dynamic mode requires you to override the florentine_ask tool so that parameters like returnTypes and requiredInputs can be supplied per request.

{
  "mcpServers": {
    "florentine": {
      "command": "npx",
      "args": ["-y", "@florentine-ai/mcp", "--mode", "static"],
      "env": {
        "FLORENTINE_TOKEN": "<FLORENTINE_API_KEY>",
        "SESSION_ID": "6f7d62f9-8ceb-456b-b7ef-6bd869c3b13a",
        "LLM_SERVICE": "openai",
        "LLM_KEY": "<YOUR_OPENAI_KEY>",
        "RETURN_TYPES": "[\"aggregation\", \"result\", \"answer\"]",
        "REQUIRED_INPUTS": "[{\"keyPath\":\"userId\",\"value\":\"507f1f77bcf86cd799439011\"}]"
      }
    }
  }
}

Authentication

Florentine MCP Server uses an API key to authenticate requests. Add the API key as an environment variable in your MCP server configuration to enable secure access.

Connect your LLM account

You bring your own LLM keys. Provide your LLM provider and key in the MCP configuration or choose to save the key in your Florentine.ai account for centralized management.

Two options exist:

Option 1 Save your LLM key in your Florentine.ai account by selecting your provider and saving the API key.

Option 2 Provide your LLM provider and API key in the MCP server configuration env vars.

"env": {
  "LLM_SERVICE": "openai",
  "LLM_KEY": "<YOUR_LLM_API_KEY>"
}

Integration Modes

You set the operating mode in the MCP server configuration to either static or dynamic.

Static mode is used when you integrate Florentine.ai into an existing MCP client and send all parameters via environment variables.

Dynamic mode is used when you integrate Florentine.ai into your own MCP client and pass parameters per request, optionally enriching them with user-specific data.

Return Types

Return types determine what the florentine_ask tool returns: the generated aggregation, the raw results, and/or a natural language answer.

You can configure return types via env or per request in dynamic mode.

Secure Data Separation for multi-tenant usage

Enable secure data separation by using Required Inputs to filter data per user or tenant. These inputs are applied to the pipeline after generation to ensure users only see data they are authorized to access.

Sessions

Sessions enable server-side chat history. You can provide a session ID to correlate interactions and improve context across requests.

Errors

All errors from the MCP Server follow a consistent JSON structure including name, statusCode, message, errorCode, and requestId. You can implement custom client error handling by parsing the content field from the error response.

florentine_list_collections

Lists all active collections with descriptions, keys and value types that can be queried.

florentine_ask

Receives a question and returns an aggregation, aggregation result, or answer depending on configured return types.