Сервер FastMCP для изучения реляционных баз данных и безопасного выполнения запросов к ним. В качестве локальной базы данных для разработки используется SQLite; SQLAlchemy также поддерживает PostgreSQL и MySQL через их драйверы.
MCP-клиент выполняет рассуждения на естественном языке и генерирует SQL. Этот сервер предоставляет инструменты для работы с базой данных, проверяет запросы только на чтение, выполняет их и возвращает структурированные результаты.
MCP client LLM -> FastMCP tools -> safety layer -> SQLAlchemy -> databaseСервер не обращается к Anthropic, поэтому ключ API Anthropic не требуется.
Related MCP server: nl2sql-mcp
Установите uv, затем из этого каталога выполните:
uv sync
uv run python tests/seed_test_db.py
uv run pytestЕсли uv ещё нет в PATH, используйте:
py -m uv sync
py -m uv run pytestБаза данных по умолчанию:
sqlite:///sample.dbЧтобы использовать другую базу данных, задайте DATABASE_URL перед запуском сервера. Примеры:
$env:DATABASE_URL = "sqlite:///C:/data/example.db"
$env:DATABASE_URL = "postgresql+psycopg2://user:password@localhost:5432/example"
$env:DATABASE_URL = "mysql+pymysql://user:password@localhost:3306/example"uv run server.pyОбщая конфигурация MCP для VS Code находится в .vscode/mcp.json. Она запускает сервер через stdio и может использоваться с MCP-совместимыми клиентами и Inspector.
Для удалённого размещения используйте Streamable HTTP:
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8000"
uv run server.pyУдалённое развёртывание должно обеспечивать аутентификацию и защищать DATABASE_URL с помощью конфигурации секретов.
explore_schema: вывести список таблиц или изучить одну таблицу
execute_query: выполнить один безопасный SELECT только для чтения
explain_query: вернуть собственный план выполнения
validate_schema: сообщать об отсутствующих первичных ключах и неиндексированных внешних ключах
suggest_index: предлагать индексы на основе метаданных таблицы или плана запроса
migration_context: предоставлять контекст схемы для генерации миграций на стороне клиента
validate_migration: проверять предлагаемые скрипты UP и DOWN без их выполнения
Каждое выполнение запроса и объяснение проходят через уровень безопасности. Изменяющие операторы, комментарии и множественные операторы отклоняются. По умолчанию результаты запросов содержат не более 100 строк.
uv run pytestНабор тестов использует временные базы данных SQLite и не требует внешних учётных данных или запущенного сервера базы данных.
См. DEPLOYMENT.md: шаги развёртывания FastMCP Horizon, требования к удалённой базе данных и контрольный список аутентификации.
Execute one validated, read-only SQL SELECT query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| row_limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full transparency burden. It does disclose that the operation is read-only and limited to one SELECT query, which is valuable. However, it does not mention row_limit behavior, validation semantics, permissions, or effect on resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff or redundancy. Every word contributes meaning, making it an efficient, front-loaded description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A completed enough for a very simple tool, especially given an output schema exists. However, it omits the row_limit behavior and does not explain what validates the query or how the tool relates to validation, leaving the user without a fully complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter semantics. The description only references the SQL query itself but does not mention row_limit or clarify how the two parameters interact. This leaves an important parameter undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Execute'), the resource ('SQL SELECT query'), and a key constraint ('read-only'). It is specific enough to differentiate from siblings like explain_query and validate_schema, though it does not explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool vs alternatives such as explain_query or validate_schema. The read-only SELECT wording implies the tool is for running queries, but it does not state exclusions or provide decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the database execution plan for one safe SELECT query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It mentions 'safe SELECT' but does not clarify what 'safe' means (e.g., read-only, no side effects) or describe any permissions, limitations, or output format. The description is too terse to adequately inform an agent about behavior beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary action and scope. Every word contributes meaning, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not explain what 'safe' means or what the execution plan looks like claiming to rely on the output schema. Since the tool has an output schemaache, return values are implicitly covered, but the description lacks details on limitations (e.g., only SELECT, read-only behavior, privileges) that are not captured elsewhere. Given the simple nature of the tool and existing output schema, it is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverageaine, so the description must compensate. The phrase 'one safe SELECT query' adds constraint that the sql parameter must be a SELECT statementable, but it does not specify allowed syntax, single-statement requirement, or other constraints. This is minimal compensation; a more detailed description of the sql parameter would be needed for a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a database execution plan for a SELECT query. This is a specific verb-resource pairing that distinguishes it from siblings like execute_query (which actually runs queries) or suggest_index (which recommends indexes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for SELECT queries only ('one safe SELECT query'), but does not explicitly state when to use this tool instead of alternatives like execute_query or suggest_index. No exclusions or alternative comparisons are provided, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explore database tables, columns, keys, indexes, and sample rows.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | No | ||
| include_sample_data | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions the tool explores tables, columns, keys, indexes, and sample rows—implying a read-only nature. However, it does not disclose specific behaviors like sample row limits, whether all tables are listed when no table_name is given, or any performance implications for large schemas. Some transparency is present, but important details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the verb and resource list. No wasted words, no redundant information. It is efficient and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and only a single parameter, the description must compensate for context. It lists what the tool explores but does not specify behavior when table_name is null (list all tables?) or provided (details for one table?), nor what 'sample rows' means (count? random? first N?). For a tool with moderate complexity and no other metadata, this is adequate but incomplete—more detail on parameters and behaviors would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines table_name as optional (string or null with default null), but the description does not explain its semantics—e.g., 'omit to list all tables' or 'specify to get details for a particular table.' Since schema coverage is limited (no descriptions in the schema), the description could have clarified how the parameter affects behavior. There is a general connection (the tool explores tables, so table_name likely filters by table), but this is only implied, not explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('explore') with a clear resource list ('database tables, columns, keys, indexes, and sample rows'). This clearly communicates the tool's function and distinguishes it from sibling tools like query execution or explanation tools. It loses one point because it doesn't explicitly differentiate itself by naming any sibling tool or stating what it does NOT do (e.g., modifications, query execution).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for exploring schema structure, which implies usage for inspection rather than data manipulation. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'use get_schema for just columns' or 'don't use this for querying data'). No exclusions or alternative tool references are given, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return schema context for client-side migration generation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions 'Return schema context' without stating whether it is read-only, what side effects (if any) exist, or performance characteristics. This is minimal and does not add meaningful transparency beyond the tool name itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose. There is no fluff or redundancy, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description need not explain return values. It is a simple no-parameter tool, and the purpose is clear. However, it could briefly mention what 'schema context' encompasses, but given the output schema and simplicity, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The description adds no param-related info because there are none, and the schema already confirms no parameters, so there is no deficiency to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'return' and the resource 'schema context' with a specific purpose 'for client-side migration generation.' This distinguishes it from siblings like 'validate_schema' or 'explore_schema' by its intended use, though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling tools, such as 'explore_schema' or 'validate_migration.' The description only states what it does, leaving the agent to infer usage context without helpful exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest indexes from a query plan or table foreign-key metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| table_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not mention side effects, permissions, or behavior when both parameters are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, clear and free of unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the output format, parameter relationships, and expected usage scenarios, making it incomplete for a tool with two optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description loosely references the parameters (query plan and table foreign-key metadata) but does not clarify their formats, constraints, or how they are used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool suggests indexes, using either a query plan or table foreign-key metadata, which distinguishes it from sibling tools like explain_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives, such as when query optimization is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate migration scripts without executing them.
| Name | Required | Description | Default |
|---|---|---|---|
| up_sql | Yes | ||
| down_sql | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of revealing behavior. It does disclose a key trait—non-execution—which is valuable for a validation tool. Nonetheless, it lacks other behavioral details (e.g., does it require a DB connection? what is the failure mode?), leaving some gaps. It adds value but not comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-constructed sentence delivers the core message with zero wasted words. It is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two string parameters, an output schema (though not shown in the prompt), and a concise description, the context is largely adequate. The description covers the essential safety aspect. Minor gaps exist: potential side-effects or prerequisites are unmentioned, but for a validation utility, the description meets most expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the parameter names 'up_sql' and 'down_sql' are self-explanatory as migration scripts. The description refers to them collectively as 'migration scripts' but adds no detail about format or constraints. The baseline is acceptable due to intuitive parameter names, but the description does not explicitly compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Validate') and resource ('migration scripts'), and adds a crucial qualifier ('without executing them') that distinguishes it from siblings like execute_query and validate_schema. This is a strong, purpose-driven statement that leaves no ambiguity about the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'without executing them' phrase implies a safe-to-run interpretation, which implicitly guides usage. However, it does not explicitly name alternatives or provide when/when-not conditions. The usage context is implied rather than stated, so it earns a mid-range score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check tables for missing primary keys and unindexed foreign keys.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only or if it has side effects, nor does it describe the output format or any side effects, making its behavior opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's function with no redundant words or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description should explain what the tool returns, but it omits that. It also lacks context about parameter semantics and usage scenarios, leaving the description incomplete for a tool with even a single parameter and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'table_name' is not explained. The description does not clarify whether it targets a specific table or all tables, nor what happens when it is null. Since the schema provides no parameter description (0% coverage), the description fails entirely to add meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to check for missing primary keys and unindexed foreign keys. This specific action distinguishes it from sibling tools like explore_schema or suggest_index, making its function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or how it differs from other validation-related tools, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0execute_queryexplain_queryexplore_schemamigration_contextsuggest_indexvalidate_migrationvalidate_schemaScored across 7 tools
Most tools have distinct purposes: exploring, executing, explaining, validating, and suggesting indexes are clearly separate. The main overlap risk is between explore_schema and migration_context, since both provide schema context, but their intended use cases differ enough to avoid serious confusion.
Six of seven tools follow a clean verb_noun pattern (explore_schema, execute_query, explain_query, validate_schema, suggest_index, validate_migration). migration_context breaks the pattern by being a noun phrase, but the overall naming style remains predictable and readable.
With 7 tools, the server is well-scoped for the stated purpose of database exploration, query execution, and migration validation. Each tool addresses a meaningful workflow step without unnecessary bloat.
The toolset covers the core read-only database workflows: schema inspection, query validation/execution/explanation, structural tenant-focused checks, index suggestions, and migration validation. No obvious dead-end exists for the server's stated purpose.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
GibsonAI MCP server: manage your databases with natural language
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
