docs: Database access MCP#54409
Conversation
gabrielcorado
added
documentation
no-changelog
gabrielcorado
temporarily deployed
to
docs-amplify
GitHub Actions
Inactive
|
Amplify deployment status
|
| `tsh mcp db` command directly starts a MCP server using the | ||
| [Standard Input/Output (stdio)](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio). |
There was a problem hiding this comment.
| `tsh mcp db` command directly starts a MCP server using the | |
| [Standard Input/Output (stdio)](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio). | |
| `tsh mcp db` command directly starts a MCP server using the | |
| [Standard Input/Output (stdio)](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport. |
| Similarly to `tsh db connect`, the database access MCP server command requires | ||
| you to pick the database user and name the MCP connections will use. In | ||
| addition, you can also filter which database will be available as an MCP | ||
| resource, either using `--query` or `--labels` flags. | ||
|
|
||
| As for the current version, **you can only specify a single value for | ||
| `--db-user` and `--db-name`**. All selected databases must have a database and | ||
| a database user. Otherwise, the queries will fail. |
There was a problem hiding this comment.
The comparison to tsh db connect suggests you can expose just single database, but I guess you can do multiple, hence the restriction on single user and database name? In any case I'd rephrase to clarify this point and show how it follows from the extra flexibility.
There was a problem hiding this comment.
hence the restriction on single user and database name?
We'll definitely improve this right after the first release. From my testing, having the model pick up the database user felt like a disaster that could happen anytime (and was insecure, especially with powerful users).
We'll probably have to develop a more robust solution (maybe adding options to roles), but we can discuss that in more depth when the time comes.
| Given that language models can perform any query on your database, we | ||
| recommend that you select a database user with only the permissions you want | ||
| to allow the language models to perform. Creating a user with read-only | ||
| permissions will prevent accidental changes to your database. |
There was a problem hiding this comment.
Huh, I thought we will do the read-only transaction trick; perhaps we can support it with a flag?
There was a problem hiding this comment.
A read-only transaction is not the solution here (as we and pgx are not doing proper input validation). The models (and users) can bypass it. So we're instead enforcing the user's selection (by CLI flags) and adding this tip/warning.
| capabilities. This guide will show you how to use the Teleport Model Context | ||
| Protocols (MCP) servers. | ||
|
|
||
| ## Database Access for MCP | ||
|
|
||
| Teleport supports serving database access as MCP servers for **PostgreSQL** | ||
| databases. |
There was a problem hiding this comment.
I think a succinct answer to the question "why would I use tsh mcp db" should be a part of the intro section.
Also, we might suggest we are open for adding support for other protocols?
| After updating your MCP client configuration, you can use the Teleport | ||
| databases. Each database protocol will have its own tool to execute queries. |
There was a problem hiding this comment.
I'd add example listing of tools here, to illustrate the point of multiple tools.
| Given that you might have multiple databases from the same protocol, the tool | ||
| call must specify which Teleport database it will perform the query against. |
There was a problem hiding this comment.
I don't quite understand this sentence, can you elaborate on this issue?
There was a problem hiding this comment.
I wanted to clarify the usage here. If you have multiple databases of the same protocol (say PostgreSQL), you must somehow indicate to the MCP client which one to use (either by text or by attaching the resource). Otherwise, it will just pick a random one.
There was a problem hiding this comment.
Ah, got it. Perhaps changing the sentence order for clarity?
The tool call must specify which Teleport database to query, since you might have multiple databases using the same protocol.
Or longer, if you prefer it:
To avoid ambiguity, the tool call must specify which Teleport database to query, as multiple databases using the same protocol may be in scope.
| The Teleport database resources can be retrieved automatically by the clients | ||
| (using the available tool) and are also available as MCP resources. Depending | ||
| on which client you're using, you can set the target database beforehand. For | ||
| example, on Claude Desktop, you can attach the resource to the conversation and | ||
| ask the model to perform the queries on the attached database. |
There was a problem hiding this comment.
Ah, so we support both tools and resources? How would that work?
There was a problem hiding this comment.
You could still attach the resource to the conversation, and the models will use it. If you don't attach or want to let the model search/select the appropriate database instance to execute the query, it can list them and have their information available.
There was a problem hiding this comment.
Sounds great. What would you say about adding examples of both usage patterns?
| After updating the configuration, you must restart the Claude Desktop app before | ||
| using the newly added MCPs. | ||
|
|
||
| ### Step 2/2. Usage |
There was a problem hiding this comment.
I think adding real-life usage example would be super helpful.
There was a problem hiding this comment.
Yeah let's give a screenshot or two to illustrate the actual usage e.g. with Claude Desktop.
| ### Troubleshooting | ||
|
|
||
| TODO |
There was a problem hiding this comment.
Scenarios/tasks to consider:
- Expired session
- Invalid database user, database name
- Some other error cases?
- How do you get the logs?
r0mant
left a comment
r0mant
left a comment
There was a problem hiding this comment.
Good start, left some feedback.
| - The Teleport Database Service configured to access a database. See one of our | ||
| [guides](../enroll-resources/database-access/guides/guides.mdx) for how to set | ||
| up the Teleport Database Service for your database. |
There was a problem hiding this comment.
This should specifically refer to a Postgres guide right? That's the only one we currently support via MCP.
|
|
||
| ### Step 1/2. Installation | ||
|
|
||
| `tsh mcp db` command directly starts a MCP server using the |
There was a problem hiding this comment.
| `tsh mcp db` command directly starts a MCP server using the | |
| `tsh mcp db` command starts a local MCP server using the |
| resource, either using `--query` or `--labels` flags. | ||
|
|
||
| As for the current version, **you can only specify a single value for | ||
| `--db-user` and `--db-name`**. All selected databases must have a database and |
There was a problem hiding this comment.
All selected databases must have a database and a database user.
What does this mean? I would expand on this here.
| } | ||
| ``` | ||
|
|
||
| #### Claude Desktop |
There was a problem hiding this comment.
Didn't we plan on having a tsh command to update it? Or did we push it out of the initial scope.
E.g. tsh mcp db login xxx (and this is where another subcommand for tsh mcp db comes handy from my comment on your other PR).
| After updating the configuration, you must restart the Claude Desktop app before | ||
| using the newly added MCPs. | ||
|
|
||
| ### Step 2/2. Usage |
There was a problem hiding this comment.
Yeah let's give a screenshot or two to illustrate the actual usage e.g. with Claude Desktop.
| `--db-user` and `--db-name`**. All selected databases must have a database and | ||
| a database user. Otherwise, the queries will fail. | ||
|
|
||
| <Admonition type="note" title="Permissions"> |
There was a problem hiding this comment.
Feels like we should move this out of admonition and into a separate Security section that explains do's and don't's. For example, permissions considerations, explicitly state that LLM will have access to the database permitted by Teleport role, the fact that it can still run any queries it will deem necessary, etc.
| { | ||
| "type": "doc", | ||
| "label": "Using Model Context Protocol (MCP)", | ||
| "id": "connect-your-client/mcp" | ||
| }, |
There was a problem hiding this comment.
Can we have a separate top-level section for MCP to increase visibility? It will be also easier to group all things MCP related under it as well.
We can keep this link here as well because it does make sense to have it under clients too, but I would have it link to the guide under main MCP section.
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
|
@gabrielcorado What's the status of this PR? Can it be taken out of draft? |
|
@r0mant The database access MCP flow changed (with the config command), so this requires some work. I'll update it and make it ready for review. |
|
Closing this in favor of #56828. Most of the comments here are either no longer applicable or have been addressed in the new branch. |
3 participants
Initial documentation for Model Context Protocol (MCP) for database access feature.
Note: The "Troubleshooting" section is still pending.