Skip to main content
Glama
andezdev

tokenlite-mysql-mcp

by andezdev

TokenLite MySQL MCP

npm version

A robust and secure MySQL database server implemented under Anthropic's Model Context Protocol (MCP). Designed specifically to solve the shortcomings of current generic MCP servers through Graceful Degradation, Active Performance Protection, and Aggressive Token Optimization.


🌟 Core Pillars

  1. Safe-Query Optimizer (AST & EXPLAIN): Protects production databases by pre-analyzing queries. Blocks unindexed Full Table Scans that exceed configurable thresholds and injects strict LIMIT clauses automatically at the AST level.

  2. Granular AST-Based Write Permissions: By default, TokenLite is 100% Read-Only. You can surgically enable specific write operations (INSERT, UPDATE, DELETE, DDL) via environment variables. The firewall uses strict AST parsing to prevent SQL injection and comment-bypass attacks, and strictly prohibits privilege escalation commands (like GRANT or CALL).

  3. Session-Level Defense in Depth: If the server is configured in strict Read-Only mode (all write variables disabled), TokenLite injects SET SESSION TRANSACTION READ ONLY directly into the connection pool sockets. This guarantees that even if a theoretical bypass exists in the AST parser, the MySQL engine itself will physically reject any data modification.

  4. Business Intelligence Injection: Bridges the gap between raw data and company logic. Automatically attaches semantic dictionaries (metadata.json) to database schema exploration, and exposes Semantic Templates via the official MCP Prompts API (templates.json) so the LLM uses pre-approved analytical queries instead of hallucinating them.

  5. Graph-Based Semantic Schema: Avoids sending giant schemas to the LLM that saturate the context window. When a table is searched, the engine uses heuristics to deduce implicit relationships and packages the exact "Auto-Join Context".

  6. CSV Token Compression: Database results are efficiently transformed into tabular CSV markdown with unambiguous NULL representation (), saving up to 50% of Output Tokens compared to verbose JSON. When results hit the applied LIMIT, a -- rows: N (truncated at LIMIT X) footer is appended so the LLM does not assume a complete dataset.

  7. MCP Completions: Table names and template keywords support the official completions/complete capability for resource templates (mysql://tables/{name}) and the query_templates prompt.


Related MCP server: Bun Database MCP Server

📋 Requirements

  • Node.js v20 or higher

  • MySQL 5.7 or higher (MySQL 8.0+ recommended)

  • A MySQL user with SELECT and SHOW VIEW privileges.


🚀 Installation & Usage

You can use this MCP server with any compatible client. Below are the configurations for the most popular ones.

1. Claude Desktop

Edit your claude_desktop_config.json (usually located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following:

Using NPX (Recommended)

{
  "mcpServers": {
    "tokenlite-mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@andezdev/tokenlite-mysql-mcp"
      ],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "your_db_user",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "MCP_EXPLAIN_MAX_SCAN_ROWS": "1000",
        "MCP_QUERY_ROW_LIMIT": "500",
        "MCP_SAFE_QUERY_ENABLE_BLOCKING": "true"
      }
    }
  }
}

2. Claude Code (CLI)

You can easily integrate this server globally into Claude Code:

claude mcp add tokenlite_mysql \
  -e DB_HOST="127.0.0.1" \
  -e DB_PORT="3306" \
  -e DB_USER="root" \
  -e DB_PASSWORD="your_password" \
  -e DB_NAME="your_database" \
  -- npx -y @andezdev/tokenlite-mysql-mcp

3. Cursor IDE

To use within Cursor IDE:

  1. Open Cursor Settings > Features > MCP.

  2. Click + Add New MCP Server.

  3. Set the Type to command.

  4. Name it tokenlite-mysql.

  5. Set the command to:

    npx -y @andezdev/tokenlite-mysql-mcp

(Note: Cursor handles environment variables directly in the IDE UI, make sure to add your DB credentials there).


⚙️ Environment Variables Reference

Understanding Query Limits (two independent knobs)

execute_safe_query applies two separate limits. Do not confuse them:

Variable

What it controls

Default

Example

MCP_EXPLAIN_MAX_SCAN_ROWS

Security gate: blocks queries whose EXPLAIN plan shows a full table scan (type: ALL) with more estimated rows than this threshold. The query is rejected before execution.

1000

5000 allows scanning tables up to ~5000 rows without an index

MCP_QUERY_ROW_LIMIT

Result cap: max rows returned to the LLM. Injected as LIMIT at the AST level. When reached, CSV includes -- rows: N (truncated at LIMIT X).

500

1000 returns up to 1000 rows per SELECT

Deprecated alias: MCP_SAFE_QUERY_MAX_ROWS still works as a fallback for MCP_EXPLAIN_MAX_SCAN_ROWS only. It does not control the result LIMIT.

Worked example with MCP_EXPLAIN_MAX_SCAN_ROWS=5000 and MCP_QUERY_ROW_LIMIT=500 on a customers table (~1502 rows):

  1. SELECT * FROM customers → passes EXPLAIN (1502 < 5000), executes with LIMIT 500, returns 500 rows + truncation footer.

  2. Same config but table has 8000 rows → blocked by EXPLAIN before execution.

Variable

Description

Default

Required

DB_HOST

MySQL Host address

localhost

No

DB_PORT

MySQL Port

3306

No

DB_USER

MySQL Username

root

No

DB_PASSWORD

MySQL Password

''

No

DB_NAME

MySQL Database name

test

Yes

MCP_EXPLAIN_MAX_SCAN_ROWS

EXPLAIN guardrail: max estimated rows for unindexed full table scans before blocking.

1000

No

MCP_QUERY_ROW_LIMIT

Max rows returned per SELECT (AST-injected LIMIT + truncation footer).

500

No

MCP_SAFE_QUERY_ENABLE_BLOCKING

Enable or disable the EXPLAIN guardrail.

true

No

MCP_METADATA_PATH

Absolute path to your custom metadata.json dictionary.

(Disabled)

No

MCP_TEMPLATES_PATH

Absolute path to your custom templates.json queries.

(Disabled)

No

TOOL_PREFIX

Prefix for tool names (useful when running multiple instances).

Derived from DB_NAME (e.g., mydb_). Random fallback only if DB_NAME is unset.

No

MCP_RATE_LIMIT_RPM

Max tool invocations per minute (sliding window). Set to 0 to disable.

60

No

MYSQL_QUERY_TIMEOUT

Max execution time for a query (in ms). Aborts heavy queries to protect against DoS.

15000

No

MYSQL_CONNECTION_LIMIT

Max concurrent pool connections.

10

No

MYSQL_CONNECT_TIMEOUT

Max time to wait for a socket to establish (in ms).

10000

No

MYSQL_RETRY_ATTEMPTS

Max retries on transient connection errors (ECONNREFUSED, PROTOCOL_CONNECTION_LOST, etc.).

3

No

MYSQL_RETRY_DELAY_MS

Base delay (ms) for exponential backoff between retries (1s, 2s, 4s...).

1000

No

MYSQL_QUEUE_LIMIT

Max queued requests when all pool connections are busy. Prevents unbounded growth if MySQL is down.

50

No

MCP_DDL_CACHE_TTL

Time-to-live (in seconds) for cached DDL statements. Reduces latency on repeated search_schema calls. Invalidated by refresh_schema.

60

No

MCP_LOG_LEVEL

Minimum severity for MCP log notifications: debug, info, notice, warning, error, critical, alert, emergency.

info

No

ALLOW_INSERT_OPERATION

Enable INSERT and REPLACE queries.

false

No

ALLOW_UPDATE_OPERATION

Enable UPDATE queries.

false

No

ALLOW_DELETE_OPERATION

Enable DELETE and TRUNCATE queries.

false

No

ALLOW_DDL_OPERATION

Enable Data Definition Language (CREATE, ALTER, DROP, RENAME).

false

No

DB_SSL

Enable TLS for the MySQL connection (recommended for managed/cloud databases).

false

No

DB_SSL_REJECT_UNAUTHORIZED

Reject self-signed or untrusted TLS certificates when DB_SSL=true.

true

No


🛡️ Business Intelligence Features (Opt-in)

TokenLite can teach the LLM about your company's business rules. To enable this, map the absolute paths of two JSON files via .env or your MCP client config:

metadata.json (Semantic Dictionary)

Translate integer statuses or internal jargon so the LLM understands the data.

{
  "orders.status": {
    "pending": "The order is waiting for payment validation",
    "shipped": "The order has left the warehouse"
  }
}

Custom Relationships

Define FK mappings the heuristic engine can't auto-detect (e.g., created_by → users). Add a _relationships key to your metadata.json:

{
  "orders.status": { "pending": "...", "shipped": "..." },
  "_relationships": {
    "orders.created_by": "users.id",
    "categories.parent_id": "categories.id"
  }
}

These are treated as authoritative (not heuristic) and take priority over automatic detection.

The heuristic engine also assigns a confidence score (0–100) to each inferred FK based on name matching (+40), data type validation (+30), primary key verification (+20), and index presence (+10). Only FKs scoring ≥70 are accepted.

templates.json (Pre-approved SQL)

Stop the LLM from hallucinating complex metrics by providing vetted templates.

[
  {
    "name": "Customer Lifetime Value (LTV)",
    "description": "Calculates total revenue generated by delivered orders per customer.",
    "sql": "SELECT c.id, SUM(oi.price) FROM customers c JOIN orders o... WHERE o.status='delivered'"
  }
]

📈 Benchmarks & Token Savings

TokenLite includes an automated benchmark suite using o200k_base tokenization (GPT-4o/GPT-5 standard) to measure efficiency improvements. Token counts are approximate — Claude 4.x uses a proprietary tokenizer; actual counts may vary slightly.

To run the benchmark in your own environment:

npm run benchmark

Baseline: Standard MCP Pattern

The benchmark compares against the standard pattern used by generic MySQL MCP servers: full schema exposed as information_schema.columns in pretty-printed JSON, and query results returned as JSON.stringify(rows, null, 2) with execution time metadata.

1. Schema Discovery (Input Tokens)

Standard MCP servers dump the entire schema to the LLM. For large databases, this consumes thousands of input tokens on every turn. TokenLite's relational graph serves a localized Auto-Join Context (target table + direct parent tables + direct child tables).

Scenario

Standard MCP Pattern

TokenLite

📉 Savings

Mock (50 tables, Enterprise CRM)

15,566 tokens

883 tokens

94.3%

Live (9 tables, Test DB)

2,208 tokens

531 tokens

75.9%

Savings scale with the number of tables: the more tables in the database, the higher the savings because the standard pattern dumps all of them while TokenLite only fetches the target + 1-hop relationships.

2. Query Result Payloads (Output Tokens)

TokenLite converts raw database rows to a dense, structured CSV layout. This avoids JSON syntax overhead (brackets, braces, repeated keys) and compresses the output payload returned to the LLM. When the row count reaches the server-injected LIMIT, results include a truncation footer (e.g. -- rows: 500 (truncated at LIMIT 500)) so agents know more data may exist.

Mock data (varied: NULLs, long descriptions, mixed lengths):

Rows Returned

Standard MCP Pattern (Tokens)

TokenLite CSV (Tokens)

📉 Output Savings (%)

10 rows

1,167

601

48.5%

50 rows

5,803

2,927

49.6%

100 rows

11,607

5,842

49.7%

500 rows

57,990

29,119

49.8%

Live data (real MySQL test database with NULLs, ENUMs, variable-length text):

Rows Returned

Standard MCP Pattern (Tokens)

TokenLite CSV (Tokens)

📉 Output Savings (%)

10 rows

1,007

628

37.6%

50 rows

5,029

3,114

38.1%

100 rows

10,071

6,232

38.1%

500 rows

50,327

31,116

38.2%


📊 Logging & Observability

TokenLite uses MCP-native logging via notifications/message instead of raw stderr output. Clients that support MCP logging (e.g., MCP Inspector) will receive structured log messages with severity levels, logger names, and JSON data.

Severity levels (from least to most severe): debug, info, notice, warning, error, critical, alert, emergency.

The server emits logs at info level and above by default. Control the minimum level via MCP_LOG_LEVEL or dynamically at runtime through the MCP logging/setLevel request.

Before the MCP session is established (e.g., during pool initialization), logs fall back to stderr.


🌐 Advanced Networking & Remote Connections

By design, tokenlite-mysql-mcp adheres to the Unix philosophy: it does one thing (AI-driven MySQL interactions) and does it securely via the standard stdio transport. It deliberately avoids bloating the codebase with HTTP servers or built-in SSH clients.

If you need to connect to remote databases or expose this server over the network, here are the recommended, enterprise-grade alternatives:

1. Connecting to Remote Databases (SSH Tunnels)

Instead of embedding SSH libraries, we recommend using native OS tunnels. This is much more secure, respects your ~/.ssh/config, and supports advanced authentication (2FA, hardware keys).

Simply open a terminal and run:

ssh -N -L 3306:127.0.0.1:3306 user@your-remote-server.com

Then, point tokenlite-mysql-mcp to localhost and port 3306.

2. Exposing the MCP Server over HTTP/Network

If you need to host this MCP Server in the cloud (AWS, GCP) and have multiple Claude desktop clients connect to it remotely via HTTP/SSE, do not modify this codebase to add Express/HTTP logic. Instead, wrap the process using standard open-source MCP proxies like mcp-proxy. This cleanly separates the transport layer security from the AI logic.

🐛 Troubleshooting

Error: OptimizerError: Full table scan detected... The LLM attempted to execute a query that requires scanning thousands of rows without using an index. Solution: Use explain_query to see the full EXPLAIN output and understand why the query was blocked. Rewrite the query with an indexed WHERE clause. If you truly need to scan the whole table, increase MCP_EXPLAIN_MAX_SCAN_ROWS in your config. To return more rows per query, adjust MCP_QUERY_ROW_LIMIT separately.

Error: calling "initialize": invalid character... This means the MCP JSON-RPC protocol crashed. Ensure you are passing the correct DB credentials and that the database is running and accessible from the machine where the MCP server runs.


Built for the AI Engineering era.


Available Tools

5 tools
mydatabase_execute_safe_queryA
Read-only

Executes a safe SELECT query on the database. Large results are automatically truncated. CRITICAL: NEVER use this tool (e.g., SHOW TABLES or querying information_schema) to understand the database structure. You MUST ALWAYS use the 'search_schema' tool first to understand the relationships and tables before writing any JOIN queries.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesSQL SELECT statement to execute.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses behavioral traits beyond annotations: it states 'Large results are automatically truncated.' This is not captured by readOnlyHint or destructiveHint. It also confirms the tool is safe and read-only, consistent with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main purpose, followed by a critical warning. Every sentence adds value, and there is no extraneous information. It is concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description adequately covers purpose, usage guidelines, and behavioral traits. It could optionally mention what the return value looks like, but this is not necessary for effective invocation. The presence of sibling tools covering schema exploration fills the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already describes 'sql' as a 'SQL SELECT statement.' The description adds no further parameter-level specifics (e.g., format, escaping), so it meets the baseline expectation but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it executes safe SELECT queries. It distinguishes itself from sibling tools by explicitly warning against using it for schema exploration, which is the role of 'search_schema'. The verb 'executes' and the resource 'safe SELECT query' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidelines: 'NEVER use this tool to understand the database structure' and 'you MUST ALWAYS use the 'search_schema' tool first before writing JOIN queries.' This gives clear when-to-use and when-not-to-use advice, along with a specific alternative tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mydatabase_explain_queryA
Read-onlyIdempotent

Returns the MySQL EXPLAIN output for a SELECT query. Use this to understand index usage, join types, and row estimates before rewriting a blocked or slow query.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesThe SELECT query to analyze.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYesEXPLAIN output rows

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds context about index usage, join types, and row estimates, but does not disclose additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words: first states purpose, second provides usage context. Highly concise and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given high schema coverage, clear annotations, and an output schema, the description is complete enough for a simple tool. It adds necessary usage context without redundancy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the parameter description in the schema already states 'The SELECT query to analyze.' The tool description adds no additional parameter semantics beyond restating that it accepts SELECT queries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns MySQL EXPLAIN output for SELECT queries, with specific verb 'Returns' and resource 'EXPLAIN output'. It distinguishes from siblings like mydatabase_execute_safe_query which executes queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context ('before rewriting a blocked or slow query') but does not explicitly state when not to use the tool or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mydatabase_pingA
Read-only

Health check: verifies the database connection is alive and returns pool stats and server version.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
statusYesWhether the database connection is healthy
server_versionNoMySQL server version
poolYes
errorNoError message if status is 'error'

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint true, and the description adds that it returns pool stats and server version, providing additional context beyond safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with 'Health check', efficient and no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple with no parameters and an output schema exists. Description covers purpose and return values sufficiently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description adds no parameter info, which is appropriate given the nature of a ping tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs a health check to verify database connection, and returns pool stats and server version. It distinguishes itself from sibling tools like execute_safe_query, explain_query, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for health checking, but lacks explicit guidance on when not to use or alternatives. Sibling tools are distinct, so no confusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mydatabase_refresh_schemaA
Read-onlyIdempotent

Forces the MCP server to rebuild the internal Schema Graph. Use this if you suspect a DBA recently added a table, column, or foreign key and the search_schema or execute queries are failing.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint: true and idempotentHint: true. The description adds that it 'forces rebuild,' which provides additional behavioral context. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the purpose. Every sentence adds value with no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description covers the tool's purpose and usage context thoroughly. Annotations provide safety cues.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema description coverage is 100%. Baseline is 4, and the description does not need to add parameter info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('forces', 'rebuild') and resource ('Schema Graph'), clearly stating the tool's purpose. It distinguishes from siblings by mentioning that it addresses failures in search_schema or execute queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use ('if you suspect a DBA recently added a table, column, or foreign key and the search_schema or execute queries are failing'). It does not mention when not to use, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mydatabase_search_schemaA
Read-only

CRITICAL TOOL FOR SCHEMA EXPLORATION: Use this tool FIRST to understand the database structure. Searches for a table and returns its exact SQL DDL, along with the DDL of its direct parent and child tables (Auto-Join Context). Do NOT use execute_safe_query for schema exploration.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe name of the table or entity to search for (e.g. 'users', 'invoices').

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations claim read-only; description adds that it returns DDL of parent/child tables. No contradiction, but could mention it's safe and read-only explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with front-loaded purpose and key guidance; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only schema tool with one parameter, the description covers return value and usage context adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already provides a solid description of the query parameter (table name). Description doesn't add extra semantics beyond what's in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it searches for a table and returns its DDL plus parent/child DDL, explicitly distinguishing from execute_safe_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use this tool FIRST for schema exploration and warns against using execute_safe_query for that purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.3/5.0
Disambiguation5/5

Each tool has a distinct purpose: executing safe SELECT queries, explaining query plans, checking connection health, forcing schema refresh, and searching schema metadata. No two tools overlap in functionality, making it easy for an agent to select the correct one.

Naming Consistency4/5

All tools follow the pattern 'mydatabase_<action>' with verbs like execute, explain, ping, refresh, search. While most are verb_noun (e.g., execute_safe_query), 'ping' is a single verb, which is a minor deviation but still clear and predictable.

Tool Count5/5

With 5 tools, the server covers essential database operations (query, explain, schema search, schema refresh, health check) without unnecessary bloat. The count is well-scoped for a focused MySQL utility.

Completeness4/5

The tool set provides good coverage for read-only database interaction and schema exploration. However, there is no tool to list all tables or columns directly; agents must rely on search_schema which requires prior knowledge of table names. This is a minor gap for full self-service discovery.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    A secure MySQL Model Context Protocol server that enables AI agents to interact with MySQL databases through standardized operations. Features comprehensive security with SQL injection prevention, connection pooling, and configurable tool access for database operations.
    1
  • F
    license
    Not graded
    quality
    D
    maintenance
    A high-performance MCP server that enables AI assistants to safely interact with MySQL databases through secure CRUD operations, schema inspection, and parameterized queries with built-in SQL injection prevention.
    1
  • A
    license
    A
    quality
    C
    maintenance
    A lightweight MySQL MCP server that enables LLMs to interact with databases through tools for schema inspection and query execution. It features LLM-friendly formatting, SSL support, and a secure read-only mode with query timeout protections.
    7
    66
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Zero-config MCP server that empowers AI agents to safely query SQL and NoSQL databases like PostgreSQL, MySQL, SQLite, MongoDB, and Redis.
    24
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/andezdev/tokenlite-mysql-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server