florentine-ai

Florentine.ai MCP サーバー - MongoDB と MySQL のデータに話しかける

Florentine.ai Model Context Protocol（MCP）サーバーを使用すると、MongoDB と MySQL のデータを自然言語でクエリする機能を、カスタム AI エージェントや AI デスクトップアプリに直接統合できます。

AI エージェントから MCP サーバーに質問が転送され、データベースクエリに変換されます。クエリの結果は、さらに処理するためにエージェントへ返されます。

また、内部には以下のような追加機能も備えています。

• マルチテナント利用向けの安全なデータ分離
• スキーマの自動探索
• 埋め込みの自動作成によるセマンティックベクトル検索／RAG のサポート
• 高度なルックアップのサポート
• キーの除外

注記： API をお探しの場合は、こちらをご覧ください。

目次

• 前提条件
• インストール
• 利用可能なツール
• 引数
• 認証
• LLM アカウントの接続
  • オプション 1：アカウントに LLM キーを保存する（推奨）
  • オプション 2：MCP サーバーの設定環境変数に LLM キーを指定する
• 統合モード
  • 静的モード
    • 環境変数
  • 動的モード
    • 例の内訳
    • florentine_ask のパラメーター
• 戻り値の型
  • 戻り値の型の指定
  • 戻り値の型の設定
• マルチテナント利用向けの安全なデータ分離
  • 必須入力の指定
  • 必須入力の設定
  • サポートされる値の型
  • 使用例
• セッション
  • セッションの指定
• エラー
  • クライアント側のカスタムエラー処理
  • よくあるエラー

前提条件

• Node.js >= v18.0.0
• Florentine.ai アカウント（こちらから無料アカウントを作成）
• 接続済みのデータベースと、Florentine.ai アカウントで分析および有効化されたコレクション／テーブルが少なくとも 1 つあること
• Florentine.ai API キー（お持ちのキーはアカウントダッシュボードで確認できます）

インストール

MCP サーバーの詳しいドキュメントは、こちらのドキュメントをご覧ください。

npx を使用して簡単にサーバーを実行できます。Claude Desktop の例（claude_desktop_config.json）は次のとおりです。

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

利用可能なツール

• florentine_list_collections --> クエリ可能な、現在有効なすべてのコレクション／テーブルを一覧表示します。説明、キー、値の型も含まれます。
• florentine_ask --> 質問を受け取り、returnTypes の設定に応じて、クエリ、クエリ結果、または回答を返します。

引数

変数	必須	許可される値	説明
--mode	はい	static, dynamic	static（Claude Desktop など、既存の外部 MCP クライアント向け）または dynamic（独自のカスタム MCP クライアント向け）です。統合モードのセクションを参照してください。
--debug	いいえ	true	外部ファイルへのログ記録を有効にします。設定する場合は、--logpath も設定する必要があります。
--logpath	いいえ	絶対ログファイルパス	デバッグログのファイルパスです。設定する場合は、--debug も設定する必要があります。

認証

Florentine.ai MCP サーバーは、リクエストの認証に API キーを使用します。アカウントダッシュボードで API キーを確認、管理できます。このキーは、MCP サーバーの設定に ENV 変数として追加する必要があります。

"env": {
  "FLORENTINE_TOKEN": "<FLORENTINE_API_KEY>"
}

LLM アカウントを接続する

Florentine.ai はBYOK（独自のキーを持ち込む）モデルとして動作するため、MCP リクエストで LLM API キー（OpenAI、Google、Anthropic、Deepseek）を指定する必要があります。

LLM API キーを追加する方法は 2 つあります。

オプション 1：アカウントに LLM キーを保存する（推奨）

LLM プロバイダーに接続する最も簡単な方法は、Florentine.ai ダッシュボードに LLM API キーを保存することです。

• API キーを追加します
• LLM プロバイダー（OpenAI、Deepseek、Google、Anthropic）を選択します
• 「Save」をクリックします

オプション 2：MCP サーバー設定の env 変数に LLM キーを指定する

Florentine.ai アカウントにキーを保存したくない場合や、複数の LLM キーを使用したい場合は、MCP サーバー設定でキーを渡すことができます。

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

パラメーター	説明	許可される値
LLM_SERVICE	使用する LLM プロバイダーを指定します。	openai,google,anthropic または deepseek
LLM_KEY	指定した LLM サービスの API キーです。	有効な API キー文字列

注： MCP サーバー設定の env 変数に LLM_KEY を指定すると、アカウントに保存されているキーよりも優先されます。

統合モード

MCP サーバー設定の args 配列で、動作モードを static または dynamic に設定する必要があります。

"args": [
  "-y",
  "@florentine-ai/mcp",
  "--mode",
  "static"
]

静的モード

Claude Desktop や Dive AI などの MCP 対応デスクトップアプリと Florentine.ai を統合する場合は、静的モードを使用してください。

static モードでは、すべてのパラメーター（戻り値の型、必須入力など）を設定 JSON 内の env 変数として指定します。つまり、設定を変更するまで、これらのパラメーターは固定されたままとなり、Florentine.ai へのすべてのリクエストで送信されます。以下の例を参照してください。

{
  "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": "[\"result\"]",
        "REQUIRED_INPUTS": "[{\"keyPath\":\"accountId\",\"value\":\"507f1f77bcf86cd799439011\"}]"
      }
    }
  }
}

環境変数

Variable	Required	Type	Description
FLORENTINE_TOKEN	はい	文字列	Florentine.ai の API キーです。ダッシュボードからコピーしてください。
SESSION_ID	いいえ	文字列	クライアントのセッション ID です。サーバー側のチャット履歴に使用されます。セッションのセクションを参照してください。
LLM_SERVICE	いいえ	文字列	使用する LLM プロバイダーを指定します。Florentine.ai アカウントに LLM キーを保存していない場合にのみ必要です。LLM アカウントの接続のセクションを参照してください。
LLM_KEY	いいえ	文字列	指定した LLM サービスの API キーです。Florentine.ai アカウントに LLM キーを保存していない場合にのみ必要です。LLM アカウントの接続のセクションを参照してください。
RETURN_TYPES	いいえ	JSON 文字列	florentine_ask ツール呼び出しの戻り値の型です。戻り値の型のセクションを参照してください。
REQUIRED_INPUTS	いいえ	JSON 文字列	必須の入力項目です。必須入力のセクションを参照してください。

動的モード

動的モードは、Florentine.ai を独自のカスタム MCP クライアントに統合する場合に使用してください。

動的モードでは、戻り値の型や必須入力など、すべてのパラメーターを florentine_ask ツールに直接渡すことができます。つまり、Florentine.ai に転送される各リクエストに、ユーザー ID などの個別のパラメーターを動的に挿入できます。

値を動的に渡せるようにするには、カスタムクライアント／エージェント内で florentine_ask ツールのメソッドを上書きする必要があります。標準の @modelcontextprotocol TypeScript SDK を使用した次の例を参照してください。

import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { fetchUserSpecificData } from './userService.js';

// Create the MCP client instance
const mcpClient = new Client({
  name: 'florentine',
  version: '1.0.0'
});

// Define MCP setup configuration
const mcpSetupConfig = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@florentine-ai/mcp', '--mode', 'dynamic'],
  env: {
    FLORENTINE_TOKEN: '<FLORENTINE_API_KEY>'
  }
});

// Connect the MCP client
await mcpClient.connect(mcpSetupConfig);

// Save original callTool function to variable
const originalCallTool = mcpClient.callTool;

// Fetch and add florentine_ask parameters dynamically (mock implementation)
const enhanceAskParameters = async ({ question }: { question: string }) => {
  return {
    question,
    // Mocking user data fetch (i.e. returnTypes, requiredInputs, etc.),
    // replace with actual implementation
    ...(await fetchUserSpecificData({ userId: '<USER_ID>' }))
  };
};

// Overwrite callTool function with custom implemention
// enhancing florentine_ask method with dynamically injected parameters
mcpClient.callTool = async (params, resultSchema, options) => {
  if (params.name === 'florentine_ask')
    params.arguments = await enhanceAskParameters(
      params.arguments as unknown as { question: string }
    );
  return await originalCallTool(params, resultSchema, options);
};

// Call to florentine_ask tool will automatically enhance parameters
const result = await mcpClient.callTool({
  name: 'florentine_ask',
  arguments: {
    question: 'Who won the last tabletennis match?'
  }
});

例の詳細

上記の例で何が起きているのか、詳しく見ていきましょう。

まず、MCP クライアントを作成して接続します。

const mcpClient = new Client({
  name: 'florentine',
  version: '1.0.0'
});

const mcpSetupConfig = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@florentine-ai/mcp', '--mode', 'dynamic'],
  env: {
    FLORENTINE_TOKEN: '<FLORENTINE_API_KEY>'
  }
});

await mcpClient.connect(mcpSetupConfig);

注記： dynamic モードでも env 変数を使用できます。ただし、パラメーターを動的に指定すると、そのパラメーターの既存の env 値は上書きされます。

次に、元の callTool 関数を変数に保存します。

const originalCallTool = mcpClient.callTool;

次に、質問を入力として受け取り、ユーザー向けの追加パラメーター（例：returnTypes、requiredInputs など）を取得して、マージしたパラメーターを返す enhanceAskParameters 関数を作成します。

const enhanceAskParameters = async ({ question }: { question: string }) => {
  return {
    question,
    // Example function that fetches additional data, e.g. user-specfic requiredInputs
    ...(await fetchUserSpecificData({ userId: '<USER_ID>' }))
  };
};

次に、元の callTool 関数を、enhanceAskParameters から取得したパラメーターで florentine_ask ツールを拡張し、変数 originalCallTool に保存しておいた元の callTool 関数を呼び出す実装で上書きします。

mcpClient.callTool = async (params, resultSchema, options) => {
  if (params.name === 'florentine_ask')
    params.arguments = await enhanceAskParameters(
      params.arguments as unknown as { question: string }
    );
  return await originalCallTool(params, resultSchema, options);
};

最後に、質問を指定して florentine_ask ツールを呼び出すと、ユーザー固有のパラメーターが動的に挿入されます。

const result = await mcpClient.callTool({
  name: 'florentine_ask',
  arguments: {
    question: 'Who won the last tabletennis match?'
  }
});

重要： florentine_ask の実装を上書きせずに、動的モードを使用しないでください。 上書きしない場合、クライアント／エージェントは、追加のパラメーターをすべて含む florentine_ask ツールの MCP サーバー側の実装を直接使用します。 そのため、クライアント／エージェントが returnTypes、requiredInputs などに設定する値を独自に決定することになります。 その結果、予期しない動作が発生し、エラーや誤った結果につながります。

florentine_ask のパラメーター

変数	必須	型	説明
sessionId	いいえ	String	クライアントのセッション ID です。サーバー側のチャット履歴に使用します。セッションのセクションをご覧ください。
returnTypes	いいえ	Array<String>	florentine_ask ツール呼び出しの戻り値の型です。戻り値の型のセクションをご覧ください。
requiredInputs	いいえ	Array<Object>	必須の入力です。必須入力のセクションをご覧ください。

戻り値の型

デフォルトでは、florentine_ask ツールは Florentine.ai アカウントで設定された結果の型を返します（デフォルト：result）。次の 3 つのステップを任意に組み合わせた returnTypes 配列を指定することで、リクエストごとに上書きできます。

1. クエリ生成：質問をデータベースクエリ（MongoDB の集計パイプラインまたは MySQL クエリ）に変換します。
2. クエリ実行：指定した接続文字列を使用して、データベースに対してクエリを実行します。
3. 回答生成：構造化された結果を自然言語の回答に変換します。

戻り値の型の指定

returnTypes 配列を指定する方法は 2 つあります。

• MCP セットアップ設定で RETURN_TYPES env 変数として指定する方法（static モードと dynamic モードで可能）
• florentine_ask ツールの returnTypes パラメーターとして指定する方法（dynamic モードでのみ可能）

env 変数として指定する場合は、値を JSON 配列の文字列として指定します。

"env": {
  "RETURN_TYPES": "[\"query\",\"result\",\"answer\"]"
}

ツールのパラメーターとして指定する場合は、値を配列として指定します。

{
  "returnTypes": ["query", "result", "answer"]
}

戻り値の種類の設定

returnTypes 配列を指定し、以下のいずれかを組み合わせることで、返却するステップを選択できます。

returnTypes の値	説明	レスポンスで期待されるキー
"query"	生成されたデータベースクエリ、使用されたデータベースとコレクション／テーブル、0〜10 の信頼度スコア、およびデータベースの種類（"mongodb" または "mysql"）を返します。	confidence、database、collection、query、databaseType
"result"	実行されたクエリの生の結果を返します。	result
"answer"	実行されたクエリの結果に基づく自然言語の回答を返します。	answer

マルチテナント利用における安全なデータ分離

必須入力と呼ばれる指定値に基づいてクエリがデータをフィルタリングするようにすることで、安全なデータ分離を有効にできます。

これらの値は、LLM によるクエリ生成後に Florentine.ai の変換レイヤーによってクエリに追加されます。そのため、Florentine.ai は各ユーザーがアクセスを許可されたデータのみを取得することを保証できます。

キーはアカウントで Required Input として定義します。設定方法については、公式ドキュメントの該当セクションを参照してください。

必須入力の指定

requiredInputs 配列を含める方法は 2 つあります。

• MCP のセットアップ設定で REQUIRED_INPUTS env 変数として指定する（static モードと dynamic モードで可能）
• florentine_ask ツールの requiredInputs パラメーターとして指定する（dynamic モードのみ可能）

env 変数として指定する場合、値は JSON 配列を文字列化して渡します。

"env": {
  "REQUIRED_INPUTS": "[{\"keyPath\":\"userId\",\"value\":\"507f1f77bcf86cd799439011\"}]"
}

ツールのパラメーターとして指定する場合、値は配列として渡します。

"requiredInputs": [
    {
      "keyPath": "userId",
      "value": "507f1f77bcf86cd799439011"
    }
  ]

複数のコレクション／テーブルに同じ keyPath を持つ Required Inputs があり、コレクション／テーブルごとに異なる value を指定する場合は、database と collections 配列も指定できます。

{
  "requiredInputs": [
    {
      "keyPath": "name",
      "value": "Sesame Street",
      "database": "rentals",
      "collections": ["houses"]
    },
    {
      "keyPath": "name",
      "value": { "$in": ["Ernie", "Bert"] },
      "database": "rentals",
      "collections": ["tenants"]
    }
  ]
}

必須入力の設定

フィールド	必須	型	説明	制約
keyPath	はい	String	フィルター対象のフィールドへのパスです。	有効なキーのパスである必要があります。
value	はい	任意	フィルターに使用する値（型ごとの詳細はサポートされる値の型を参照してください）。	フィールドの型（String、ObjectId、Boolean、Number、Date）と一致する必要があります。
database	いいえ	String	フィルター対象のコレクションを含むデータベースです。	collectionsを指定する場合は必須です。
collections	いいえ	Array<String>	フィルターを適用する、データベース内の特定のコレクション／テーブルです。	1つ以上のコレクション／テーブルを含める必要があります。

サポートされる値の型

キーの値の型に応じて、Required Inputの値として指定できる内容が異なります。

型	形式の例	サポートされる演算子	備考
String or Array<String>	"text" { $in: ["text1", "text2"] }	$in	大文字と小文字を区別します。
ObjectId or Array<ObjectId>	"507f191e810c19729de860ea" { $in: ["507f191e810c19729de860ea", "507f191e810c19729de860eb"] }	$in	文字列として指定します。
Boolean	true/false	—	完全一致する値のみです。
Number or Array<Number>	42 { $gt: 10, $lte: 100 } { $in: [1, 2, 3] } { $in: [{$gte:1}, {$lt:10}] }	$gt、$gte、$lt、$lte、$in	小数に対応しています。
Date or Array<Date>	"2024-01-01T00:00:00Z" (UTC) "2024-01-01T00:00:00-05:00"(タイムゾーンオフセット)	$gt、$gte、$lt、$lte、$in	ISO 8601 形式です。

使用例

注記： ツールのパラメーター入力としてのみ例を提供します。env の実装では、キー名を REQUIRED_INPUTS に変更し、JSON を文字列化してください。

例の型： String

ユースケース： ユーザーが、頻繁に一緒にプレイするプレイヤーの統計情報のみを閲覧できるようにします。

解決策： プレイヤー名でアクセスを制限し、4 人のプレイヤーのグループに限定します。

const res = await FlorentineAI.ask({
  question: 'Which player had the most wins?',
  requiredInputs: [
    {
      keyPath: 'name',
      value: { $in: ['Megan', 'Frank', 'Jen', 'Bob'] }
    }
  ]
});

例の型： ObjectId

ユースケース： ユーザーが、自分の商品の売上のみを閲覧できるようにします。

解決策： accountId でアクセスを制限し、特定のアカウント 1 つに限定します。

const res = await FlorentineAI.ask({
  question: 'Whats the revenue of my products?',
  requiredInputs: [
    {
      keyPath: 'accountId',
      value: '507f1f77bcf86cd799439011'
    }
  ]
});

例の型： Boolean

ユースケース： 顧客の分析はすべて、有料顧客のみを対象に実施する必要があります。

解決策： isPaidAccount でアクセスを制限し、有料顧客のみに限定します。

const res = await FlorentineAI.ask({
  question: 'How many customers registered in the last year?',
  requiredInputs: [
    {
      keyPath: 'isPaidAccount',
      value: true
    }
  ]
});

例の型： Number

ユースケース： 従業員が、一定金額未満の支払い情報のみを閲覧できるようにします。

解決策： amount でアクセスを制限し、10.000 未満の支払いに限定します。

const res = await FlorentineAI.ask({
  question: 'List all payments we received.',
  requiredInputs: [
    {
      keyPath: 'amount',
      value: { $lt: 10000 }
    }
  ]
});

例の型： Date

ユースケース： 財務データの分析対象を特定の 1 年間のみにします。

解決策： transactionDate でアクセスを制限し、2024 年のすべての取引に限定します。

const res = await FlorentineAI.ask({
  question: 'What was our revenue, profit and margin per month?',
  requiredInputs: [
    {
      keyPath: 'transactionDate',
      value: {
        $gte: '2023-01-01T00:00:00Z',
        $lt: '2024-01-01T00:00:00Z'
      }
    }
  ]
});

セッション

セッションを使用すると、Florentine.ai はサーバー側のチャット履歴を有効化できます。

MCP サーバーを含むクライアント／エージェントは通常、チャット履歴を自ら管理するため、セッションの追加は必須ではありません。

ただし、セッションを追加すると、Florentine.ai がコンテキストをより適切に把握し、結果の品質が向上する可能性があります。

セッションの指定

sessionId を含める方法は 2 つあります。

• MCP のセットアップ設定で SESSION_ID env 変数として指定する（static モードと dynamic モードで利用可能）
• florentine_ask ツールの sessionId パラメーターとして指定する（dynamic モードでのみ利用可能）

env 変数として指定する場合：

"env": {
  "SESSION_ID": "<YOUR_SESSION_ID>"
}

ツールのパラメーターとして指定する場合：

{
  "sessionId": "<YOUR_SESSION_ID>"
}

エラー

MCP サーバーのツール呼び出しから返されるすべてのエラーは、次の一貫した JSON 構造に従います。

{
  "error": {
    "name": "FlorentineApiError",
    "statusCode": 500,
    "message": "The provided Florentine API key is invalid. You can find the key in your account settings: https://florentine.ai/settings",
    "errorCode": "INVALID_TOKEN",
    "requestId": "abc123"
  }
}

フィールド	型	説明
name	string	エラークラス名（例：FlorentineApiError、FlorentineConnectionError）
statusCode	number	HTTP ステータスコード（例：400、500）
message	string	エラーの内容の説明
errorCode	string	エラー識別子（例：NO_TOKEN、INVALID_LLM_KEY）
requestId	string	このリクエストの一意の ID（サポートへの問い合わせやデバッグに役立ちます）

カスタムクライアントでのエラー処理

エラーオブジェクトは、文字列化された JSON として content 配列に返されます。

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"name\":\"FlorentineApiError\",\"statusCode\":401,\"message\":\"The provided Florentine API key is invalid. You can find the key in your account settings: https://florentine.ai/settings\",\"errorCode\":\"INVALID_TOKEN\",\"requestId\":\"uhv99g\"}}"
    }
  ],
  "isError": true
}

text 内の JSON を解析し、カスタムクライアント／エージェントでさまざまなエラーを処理できます。

一般的なエラー

エラー名	errorCode	意味
FlorentineApiError	MODE_MISSING	モード引数として static または dynamic を指定する必要があります
FlorentineApiError	MODE_INVALID	モードが無効です（static または dynamic である必要があります）
FlorentineApiError	INVALID_TOKEN	Florentine API キーが無効です
FlorentineApiError	LLM_KEY_WITHOUT_SERVICE	llmKey が定義されている場合は llmService を指定する必要があります
FlorentineApiError	LLM_SERVICE_WITHOUT_KEY	llmService が定義されている場合は llmKey を指定する必要があります
FlorentineApiError	INVALID_LLM_SERVICE	指定された llmService が無効です
FlorentineApiError	NO_OWN_LLM_KEY	独自の LLM キーを指定する必要があります
FlorentineApiError	NO_ACTIVE_COLLECTIONS	アカウントで有効になっているコレクション／テーブルがありません
FlorentineApiError	MISSING_REQUIRED_INPUT	必須入力がありません
FlorentineApiError	INVALID_REQUIRED_INPUT	必須入力が無効です
FlorentineApiError	INVALID_REQUIRED_INPUT_FORMAT	必須入力の形式が無効です
FlorentineApiError	NO_QUESTION	質問がありません
FlorentineApiError	EXECUTION_FAILURE	作成したクエリの実行に失敗しました
FlorentineApiError	NO_CHAT_ID	履歴チャット ID が必要ですが、指定されていません
FlorentineApiError	TOO_MANY_TOKENS	クエリのプロンプトが LLM モデルの最大トークン数を超えています
FlorentineLLMError	API_KEY_ISSUE	LLM API キーが無効です
FlorentineLLMError	NO_RETURN	Florentine.ai が有効な LLM の応答を受信しませんでした
FlorentineLLMError	RATE_LIMIT_EXCEEDED	LLM リクエストのサイズが大きすぎます
FlorentineConnectionError	CONNECTION_REFUSED	クエリ実行用のデータベースに接続できませんでした
FlorentineCollectionError	NO_EXECUTION	作成したクエリを実行できませんでした
FlorentinePipelineError	MODIFICATION_FAILED	クエリパイプラインの変更に失敗しました
FlorentineUsageError	LIMIT_REACHED	プランに含まれる API リクエストをすべて使い切りました
FlorentineUnknownError	UNKNOWN_ERROR	発生した不明なエラー