# TiDB Cloud MCP > TiDB Cloud (Serverless Distributed SQL) MCP Server lets you manage your entire database infrastructure through chat. You can list every project, check specific cluster details, and pull a full inventory of all TiDB X instances across different tiers—all without opening the web console. ## Overview - **Category:** databases - **Price:** Free - **Tags:** tidb, distributed-sql, serverless-database, cloud-database, database-management ## Description You don't gotta open up a console or click through ten different dashboards to manage your TiDB Cloud setup anymore. Just connect your AI client, and your agent handles all the dirty work of talking directly to your database infrastructure. This server gives you command-line access to everything running in your organization. If you need an overview, start by getting a full map of where your resources live. You can run `list_projects` to see every single project accessible across your entire TiDB Cloud account. That's your master list. Once you know which environment you’re dealing with, you use `get_project` to pull the detailed metadata and specific IDs for any one project by its name or ID. This gives you a deep dive into that environment’s setup without leaving the chat window. When it comes to your actual data stores, checking inventory is simple but crucial. Running `list_instances` pulls up a complete count of every TiDB X instance—you're talking Starter, Essential, and Premium tiers—that you've got running inside all those projects. This single call gives you the full scope of what’s active right now. You won't miss a thing. For performance-critical stuff, you need to inspect the cluster topology. You use `list_clusters` to get a list and details on dedicated database clusters within a specific project. These are your high-performance setups; this tool lets you check their status and structure quickly for auditing or planning upgrades. It's key for understanding how your core data is actually laid out. The whole point here is that you bypass the UI friction. Instead of clicking through menus, your agent uses these tools to extract precise information: it gets the project names needed for scripting, pulls specific resource counts from `list_instances`, or maps out the physical structure using `list_clusters`. It streamlines checking whether a particular instance needs patching or if a whole project's metadata is up-to-date. You simply tell your agent what you need to know—like "Show me all Premium instances in Project Alpha"—and it runs the necessary sequence of calls and spits out the actionable data right here. You’ll save yourself hours of clicking around in the web console just managing IDs, checking resource allocation across multiple environments, or confirming that every single required cluster is online and healthy. ## Tools ### get_project Retrieves detailed information for a single specified project. ### list_clusters Gets a list of all dedicated database clusters within a specific project. ### list_instances Pulls an inventory of all TiDB X instances running inside your projects. ### list_projects Returns a list of every project accessible in your entire organization. ## Prompt Examples **Prompt:** ``` List all my TiDB Cloud projects. ``` **Response:** ``` I've retrieved your projects. You have 3 active projects: 'Production-DB' (ID: 101), 'Staging-Env' (ID: 102), and 'Analytics-Data' (ID: 103). Which one would you like to inspect? ``` **Prompt:** ``` Show me all TiDB X instances in project 101. ``` **Response:** ``` In project 101, I found 2 instances: a 'Serverless Starter' instance in us-east-1 and a 'Premium' instance in eu-west-1. Both are currently running. ``` **Prompt:** ``` Get the details for dedicated clusters in project 103. ``` **Response:** ``` Checking dedicated clusters for project 103... I found one Dedicated cluster named 'Analytics-Main' with 3 TiKV nodes and 2 TiDB nodes. It is healthy and active. ``` ## Capabilities ### List all organizational projects Retrieves a full list of every accessible project within your TiDB Cloud organization. ### Get specific project details Fetches detailed metadata and IDs for one specified project using its name or ID. ### List all database instances Retrieves a complete inventory of every TiDB X instance (Starter, Essential, Premium) housed across your projects. ### Inspect dedicated clusters Lists and provides details on dedicated cluster topologies for high-performance database inspection. ## Use Cases ### Debugging a deployment failure The new backend engineer runs into an API error related to a missing resource ID. Instead of asking a colleague, they prompt their agent: 'What are all the project IDs?' The agent uses `list_projects`, providing them with the exact list needed to resolve the bug immediately. ### Quarterly infrastructure audit A DBA needs to report on resource utilization for compliance. They ask their agent to 'List all projects and count instances.' The agent chains `list_projects` then calls `list_instances` per project, giving the DBA a comprehensive, structured report. ### Pre-migration validation A DevOps team is planning a major database upgrade. They run 'Show me all dedicated clusters' using `list_clusters`. This confirms that every critical high-performance topology exists and is accounted for before they start the migration scripts. ### Resource scoping check An engineer wonders if a specific microservice runs in 'Staging'. They ask, 'What projects exist?' The agent uses `list_projects`, allowing the engineer to visually confirm that the 'Staging-Env' project exists and then drill down with `get_project`. ## Benefits - Audit resource scope fast. Instead of clicking through menus to see what's running where, use `list_projects` first. You get a flat list of all organizational containers so you know exactly where your data lives. - Check every instance in one go. The `list_instances` tool pulls the full inventory—Starter, Essential, Premium—so you don't have to guess which cluster has which service tier. - Pinpoint specific resource details. Need a Project ID for a script? Run `get_project` to pull deep metadata without manual copy-pasting from a dashboard view. - Audit high-performance setups. Use `list_clusters` to get a clear, immediate breakdown of dedicated cluster topologies. Perfect for pre-migration checks. - Eliminate web console hopping. You keep all your resource data—project IDs, instance counts, cluster names—inside your chat window, making debugging much faster. ## How It Works The bottom line is: you send an intent to your agent, and it executes the correct API call using these tools. 1. Subscribe to the server and input your TiDB Cloud Public and Private API Keys. 2. Your AI client (Claude, Cursor, etc.) runs a command like 'list all projects.' 3. The MCP Server calls the appropriate tool (`list_projects`) and returns structured data that your agent uses for conversation. ## Frequently Asked Questions **How do I list all the projects using the get_project tool?** You don't use `get_project` to list everything; that tool requires a specific ID. To see all available scopes, you must run `list_projects`. That function gives you the full organizational overview first. **Can I find out every single running instance with list_instances?** Yes, `list_instances` pulls a complete inventory of all TiDB X instances—regardless of whether they're Starter or Premium. It gives you the full picture in one call. **What is the difference between list_clusters and list_instances?** They track different things. `list_instances` handles individual database nodes (the X instances). `list_clusters` focuses specifically on grouping those resources into a high-performance Dedicated cluster topology. **Does this MCP Server help me check project details?** Absolutely. Use the `get_project` tool and provide the specific Project ID you need. It retrieves all relevant metadata for that single, specified environment. **What credentials do I need to use the list_projects tool?** You must provide both your TiDB Cloud Public and Private API Keys when setting up the server. These keys allow your AI agent to authenticate against your account, ensuring you only see resources you have access to. **If I run list_clusters for a project, but no dedicated clusters exist, what response should I expect?** The tool returns a specific, non-error message stating that zero clusters were found. This clear output allows your agent to proceed with other tasks without assuming failure. **When using list_instances, can I filter the results by database tier (e.g., Premium)?** Yes, you pass a scope parameter to refine instance retrieval. This allows you to pull data only for specific tiers—like Starter or Essential—without processing unrelated records. **Are there any rate limits when calling list_projects?** The server adheres strictly to TiDB Cloud’s API rate limits. If you exceed the allowed number of calls, your agent will receive a standard 429 error code until your usage window resets. **Can I see both serverless and dedicated clusters with this server?** Yes. Use `list_instances` to see TiDB X instances (Serverless/Starter/Premium) and `list_clusters` to view your Dedicated cluster infrastructure. **How do I get the ID of a specific project to query its instances?** You can run the `list_projects` tool first. It will return a list of all accessible projects along with their unique IDs, which you can then use in `list_instances` or `list_clusters`. **Does this tool allow me to delete or create new clusters?** No. The current version of the TiDB Cloud MCP server is focused on discovery and inspection (read-only operations) such as `list_projects`, `get_project`, and `list_clusters` to ensure safe infrastructure monitoring.