Initial PostgreSQL MCP support by gabrielcorado · Pull Request #54431 · gravitational/teleport

gabrielcorado · 2025-05-01T02:56:32Z

The initial version of the database access MCP is for PostgreSQL databases. Docs preview PR

For reviewers, here is a quick overview of the entire flow:

Receive a list of databases available on the MCP server.
Check each database's corresponding MCP server (per protocol). This is done using a simple Registry that maps MCP server constructors using database protocols.
If there is no match, the database is skipped. Otherwise, we start an ALPN local proxy for each database.
After that, we start the MCP servers, passing the databases they will serve.
Start the "Root" MCP server, which, in addition to all tools registered by the protocol-specific MCPs, has the served database as a resource and a tool to list them.

What is not currently covered:

Automatically refresh the list of served databases. For example, if the user now has access to a different database, they'll need to restart the MCP command to get access to it.

Claude Desktop sample usage

# claude_desktop_config.json
{
  "mcpServers": {
    "teleport-databases": {
      "command": "tsh",
      "args": [
        "mcp",
        "db",
        "start",
        "teleport://databases/pg-dev?dbUser=postgres&dbName=postgres",
        "teleport://databases/pg-prod?dbUser=readonly&dbName=postgres"
      ]
    }
  }
}

greedy52

🎉 ship it

public-teleport-github-review-bot · 2025-05-16T02:50:05Z

@gabrielcorado - this PR will require admin approval to merge due to its size. Consider breaking it up into a series smaller changes.

gabrielcorado · 2025-05-28T18:17:44Z

I've updated the implementation to better fit the login command (which will be added in a separate PR). The changes were:

tsh mcp db start now receives a list of databases in the MCP resources format. The resource URI will also include the connection parameters (database user and database name). This way, users can tweak their configuration and access different databases without requiring a branch. (see PR description for a config example).
The filtering options --query and --labels will be available on the tsh mcp db login command.
The tsh MCP db start command is now hidden, as manually running it on the terminal is ineffective. Users must rely on the login command to generate the correct command.

The new UX flow would consist of users running the login command, which will generate the final tsh mcp db start command and update their MCP client.

r0mant

lgtm

r0mant · 2025-05-28T23:44:11Z

+)
+
+// databaseURITemplate template used to parse database resource URIs.
+var databaseURITemplate = urlpath.New("/databases/:name")


Should we include the cluster name here? To be able to add support for trusted clusters in future for example.

if we gonna support more resources and trusted cluster, might just adopt the same scheme Connect uses:

teleport/lib/teleterm/api/uri/uri.go

Lines 31 to 32 in 2365ae9

var pathDbs = urlpath.New("/clusters/:cluster/dbs/:dbName")

var pathLeafDbs = urlpath.New("/clusters/:cluster/leaves/:leaf/dbs/:dbName")

I've updated to include the cluster information.

r0mant · 2025-05-28T23:45:00Z

+// path returns the resoruce URI full path. For resources, we must include the
+// hostname as it indicates the resource type.
+func (u ResourceURI) path() string {
+	return "/" + u.url.Hostname() + u.url.Path


Nit: Use path.Join here?

We cannot use the URL.JoinPath because part of the resource URI is parsed into the url.Host, which we want included here.

greedy52 · 2025-05-29T14:32:47Z

+	// otherwise the MCP clients will be stuck waiting for a response.
+	tc.NonInteractive = false
+
+	uris := make([]*mcp.ResourceURI, len(c.databaseURIs))


how do we deal with duplicates? or worse, same database service with different query params

I've added a validation for the duplication. The current resource URI wouldn't support a single database configured multiple times.

camscale · 2025-06-05T16:32:41Z


 // InitLogger configures the global logger for a given purpose / verbosity level
-func InitLogger(purpose LoggingPurpose, level slog.Level, opts ...LoggerOption) error {
+func InitLogger(purpose LoggingPurpose, level slog.Level, opts ...LoggerOption) (*slog.Logger, error) {


This signature change has broken tsh vnet on darwin:

teleport/tool/tsh/common/vnet_daemon_darwin.go

Line 64 in 1fba70d

if err := utils.InitLogger(utils.LoggingForDaemon, level, utils.WithOSLog(subsystem)); err != nil {

- probably got missed due to build tags.

* feat(mcp): initial postgres mcp * test(postgres): fix missing mock function * fix(gomod): go mod tidy all * refactor: code review suggestions * fix(tsh): mcp init missing logger * chore(tsh): missing other route to database field * refactor: use in-memory net listener * test(tsh): add mcp db command test * chore: fix license * refactor(tsh): move logger init * test(mcp): sort slices to avoid flakiness * chore: fix lint * test(mcp): sort the resources before assertion * fix(mcp): update error handler for better message * refactor: code review suggestions * feat: add external error retriever for more accurate error messages * refactor: use the same logger init for mcp purposes * refactor: code review suggestions * refactor(tsh): rename command to `tsh mcp db start` * refactor(mcp): protect database resources with rw mutex * chore: update server godocs * chore: go mod tidy * refactor: update command to take list of databases * chore(mcp): license * chore(tsh): remove unused function * refactor: code review suggestions * refactor(tsh): validate duplicated databases in MCP configuration * refactor(tsh): rename files to mcp_db * feat(mcp): add cluster name to the database resource

* Initial PostgreSQL MCP support (#54431) * feat(mcp): initial postgres mcp * test(postgres): fix missing mock function * fix(gomod): go mod tidy all * refactor: code review suggestions * fix(tsh): mcp init missing logger * chore(tsh): missing other route to database field * refactor: use in-memory net listener * test(tsh): add mcp db command test * chore: fix license * refactor(tsh): move logger init * test(mcp): sort slices to avoid flakiness * chore: fix lint * test(mcp): sort the resources before assertion * fix(mcp): update error handler for better message * refactor: code review suggestions * feat: add external error retriever for more accurate error messages * refactor: use the same logger init for mcp purposes * refactor: code review suggestions * refactor(tsh): rename command to `tsh mcp db start` * refactor(mcp): protect database resources with rw mutex * chore: update server godocs * chore: go mod tidy * refactor: update command to take list of databases * chore(mcp): license * chore(tsh): remove unused function * refactor: code review suggestions * refactor(tsh): validate duplicated databases in MCP configuration * refactor(tsh): rename files to mcp_db * feat(mcp): add cluster name to the database resource * fix(tsh): update InitLogger return type (#55479) * MCP access part 1: update app definition and config (#54706) * MCP access part 1: update app definition and config * address feedback * make -C integrations/operator crd * MCP access part 2: new role options, access checker, role editor (#54734) * MCP access part 2: new role options, access checker, role editor * catch unsupported mcp fields * simplify mcpToolsToModel * MCP access part 3: audit events and reporting (#54779) * MCP access part 3: audit events and reporting * add new icon, storybook, format * MCP access part 4: mcputils (#54880) * MCP access part 4: mcp helpers * address feedback * address comment, minor edits * update mcp-go * MCP access part 5: Claude desktop config parser (#55179) * claude desktop config * rework * split Config to Config and FileConfig * add a comment on unofficial linux * MCP access part 6: "tsh mcp ls" (#55292) * MCP access part 6: "tsh mcp ls" * address feedback * MCP access part 7: MCP app in Web UI (#55306) * MCP access part 7: MCP app in Web UI * Make spacing in modal closer to what's in database modal * add mcp app to ResourceActionButton.story.tsx * move AppSubKind to shared/services/types. * remove --format claude (not needed see part 8) * add jsdoc --------- Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com> * MCP access part 8: tsh mcp config (#55370) * MCP access part 8: tsh mcp login/logout * change to --format and --config-file * switch to config and drop logout * enable debug by default * remove unused ut functions * MCP access part 9: tsh mcp connect, stub server, integration test (#55547) * MCP access part 9: tsh mcp connect, stub server, integration test * fix tests and lint * MCP access part 10: server handler (#55644) * MCP access part 10: server handler * address feedback and fix docker tests * add more comments * minor lint fix * move set logger default after other checks * Implement `tsh mcp db config` (#55781) * feat(tsh): add `tsh mcp db config` subcommand * chore(claude): fix lint * refactor: code review suggestions * refactor: code review suggestions * test(tsh): add missing option on test case * chore(tsh): add message on manually adding database URI * Refactor MCP database access to dial ALPN proxy directly (#55836) * refactor: dial database instead of using local proxy for MCP servers * refactor: review suggestions * manual fixes * tctl users add/update to support mcp tools trait (#56771) * tctl users add/update to support mcp tools trait * revert empty slice capability * Enhances MCP servers usage with Cursor (#56474) * feat(mcp): enhances MCP servers usage with Cursor * refactor: code review suggestions * mcputils refactor and new mcptest package (#56010) * mcp server and mcputils refactor * mcptest package * allow testing in mcptest * Teleport MCP demo server (#56637) * Teleport MCP demo server * replace guide tool with session tool, and switch to resource label * add new flag to teleport configure * replace teleport_session_id with mcp_transport_type * feat(gomod): update mcp-go to v0.32.0 * eslint-disable-next-line (same in master) --------- Co-authored-by: Gabriel Corado <gabriel.oliveira@goteleport.com> Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>

feat(mcp): initial postgres mcp

c657625

gabrielcorado requested review from GavinFrazar, Tener, greedy52 and r0mant May 1, 2025 02:56

gabrielcorado added 2 commits May 1, 2025 00:14

test(postgres): fix missing mock function

c823e69

fix(gomod): go mod tidy all

42d9402

greedy52 reviewed May 9, 2025

View reviewed changes

Tener reviewed May 12, 2025

View reviewed changes

Comment thread lib/client/db/mcp/errors.go Outdated

Comment thread lib/client/db/postgres/mcp/mcp.go Outdated

greedy52 added this to the MCP access MVP (v18.1.0) milestone May 12, 2025

gabrielcorado added 8 commits May 15, 2025 15:56

refactor: code review suggestions

a0d95ed

Merge branch 'master' into gabrielcorado/pg-mcp-init

a5a24ee

fix(tsh): mcp init missing logger

2623b70

chore(tsh): missing other route to database field

c3c4cc5

refactor: use in-memory net listener

1cfcf9c

test(tsh): add mcp db command test

f2dcd6e

chore: fix license

10f7bf5

refactor(tsh): move logger init

db60260

gabrielcorado marked this pull request as ready for review May 16, 2025 02:49

gabrielcorado requested review from Tener and greedy52 May 16, 2025 02:49

github-actions Bot requested review from Joerger and espadolini May 16, 2025 02:50

github-actions Bot added size/xl tsh tsh - Teleport's command line tool for logging into nodes running Teleport. labels May 16, 2025

test(mcp): sort slices to avoid flakiness

ab10408

espadolini removed their request for review May 16, 2025 07:56

Tener reviewed May 16, 2025

View reviewed changes

Comment thread lib/utils/listener/memory.go

Comment thread tool/tsh/common/mcp.go Outdated

Tener approved these changes May 16, 2025

View reviewed changes

gabrielcorado requested review from GavinFrazar, Tener, greedy52 and r0mant May 28, 2025 18:17

gabrielcorado added the no-changelog Indicates that a PR does not require a changelog entry label May 28, 2025

chore(tsh): remove unused function

c6237b3

r0mant approved these changes May 28, 2025

View reviewed changes

greedy52 reviewed May 29, 2025

View reviewed changes

greedy52 removed the do-not-merge label May 29, 2025

public-teleport-github-review-bot Bot removed the request for review from Joerger May 29, 2025 15:12

gabrielcorado added 6 commits June 4, 2025 12:20

refactor: code review suggestions

5c8924d

refactor(tsh): validate duplicated databases in MCP configuration

4d3775b

refactor(tsh): rename files to mcp_db

ac5716b

Merge branch 'master' into gabrielcorado/pg-mcp-init

7888d75

feat(mcp): add cluster name to the database resource

4662050

Merge branch 'master' into gabrielcorado/pg-mcp-init

fed7970

gabrielcorado enabled auto-merge June 4, 2025 20:22

gabrielcorado added this pull request to the merge queue Jun 4, 2025

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jun 4, 2025

gabrielcorado added this pull request to the merge queue Jun 4, 2025

Merged via the queue into master with commit 639992c Jun 4, 2025
39 checks passed

gabrielcorado deleted the gabrielcorado/pg-mcp-init branch June 4, 2025 21:38

camscale reviewed Jun 5, 2025

View reviewed changes

gabrielcorado mentioned this pull request Jun 5, 2025

Fix InitLogger call expecting single return type #55479

Merged

greedy52 mentioned this pull request Jun 26, 2025

[v18] MCP access #56143

Merged

greedy52 mentioned this pull request Jul 8, 2025

Teleport Database MCP server #56585

Closed

	var pathDbs = urlpath.New("/clusters/:cluster/dbs/:dbName")
	var pathLeafDbs = urlpath.New("/clusters/:cluster/leaves/:leaf/dbs/:dbName")

Conversation

gabrielcorado commented May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greedy52 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

public-teleport-github-review-bot Bot commented May 16, 2025

Uh oh!

Uh oh!

Uh oh!

gabrielcorado commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

r0mant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

r0mant May 28, 2025

Choose a reason for hiding this comment

Uh oh!

greedy52 May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabrielcorado Jun 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

r0mant May 28, 2025

Choose a reason for hiding this comment

Uh oh!

gabrielcorado Jun 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

greedy52 May 29, 2025

Choose a reason for hiding this comment

Uh oh!

gabrielcorado Jun 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

camscale Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

gabrielcorado commented May 1, 2025 •

edited

Loading

gabrielcorado commented May 28, 2025 •

edited

Loading

greedy52 May 29, 2025 •

edited

Loading