diff --git a/rfd/0221-mcp-gateway.md b/rfd/0221-mcp-gateway.md new file mode 100644 index 0000000000000..de5026126c527 --- /dev/null +++ b/rfd/0221-mcp-gateway.md @@ -0,0 +1,129 @@ +--- +authors: Gabriel Corado (gabriel.oliveira@goteleport.com) +state: draft +--- + +# RFD 0221 - MCP Gateway + +## Required Approvers + +* Engineering: @r0mant && @greedy52 +* Product: @klizhentas + +## What + +A single local MCP server that can serve all Teleport MCPs to clients, +providing a single experience for managing configurations and troubleshooting +issues. + +## Why + +The MCP local gateway reduces the operational overhead of setting up each +resource by allowing clients to integrate once instead of editing configurations +for each new server. It complements the current approach while improving +visibility of runtime failures, providing actionable errors, and centralizing +remediation in Teleport Connect/`tsh`. + +## UX + +The MCP gateway is available in both tsh and Teleport Connect. This section +mainly focuses on integration within Teleport Connect, with a brief subsection +on MCP gateway usage in `tsh` at the end. + +### Guiding users into knowing Teleport's MCP capabilities and features + +Previously, Teleport Connect did not support launching or connecting to MCP +applications. Now, users will see a "Connect" button on MCP applications and an +additional connect option for supported databases. By clicking it, they will +enable the server on the gateway. + +Unified Resources view in Connect with MCP support + +When enabling a resource as an MCP server for the first time, Teleport Connect +will display a modal allowing users to install the Teleport gateway MCP on their +preferred client. The modal will offer a one-click install option for user +clients and a sample configuration that can be customized for other clients. + +Configure MCP clients dialog in Connect + +With the clients configured, users can now enable or disable the MCP servers, +including supported databases. This will impact all connected clients. + +Unified Resources view in Connect with MCP servers enabled + +### Managing MCP Gateway + +The MCP Gateway remains a permanent fixture in the UI within the connection +list at the top left. + +Connections view in Connect with MCP option + +Clicking on the MCP item opens a dedicated MCP Gateway panel within the +connection list. The panel features a button for managing the MCP clients' +installation server and also shows a list of enabled resources. + +MCP connection in Connect with servers enabled + +If users enable MCP servers but have no clients configured, the MCP connection +will show a warning, emphasizing that turning servers on or off does not affect +any clients and that some action is needed to complete the setup. + +MCP connection in Connect with missing MCP client configuration + +### Expired credentials + +Given an MCP client already configured with some MCP servers enabled, once the +user credentials expire, the gateway will maintain their last view of tools +unchanged. However, tool calls will still send a message guiding users to +Teleport Connection, which will prompt them to re-login. + +### Identifying and resolving issues + +With the MCP, clients are configured, and MCP servers are enabled. After the MCP +client initializes the session, the gateway can monitor each connection and +detect potential issues. The most common issues will be mapped, and resolution +instructions will be displayed to users. + +MCP connection in Connect with MCP server errors + +Besides the reported issues, Teleport Connect will also have access to the +gateway logs. This will be shown in a separate tab with a save/export button so +users can share this information on support tickets. + +It's important to note that without an MCP client configured, no diagnosis or +logs will be available. This is mainly because Teleport Connect won't initialize +the MCP sessions. In the future, we can develop a diagnosis process that acts +like an MCP client and initializes the session to ensure the MCP server starts +properly. + +### Restoring configured MCP servers + +The enabled servers and their options will be saved as user preferences, so +logging in to a different cluster or computer will automatically update the +gateway configuration. + +### `tsh` + +A new set of commands will be added, all of which will relate to installing and +managing the MCP gateway. + +```code +# Installing MCP gateway in different clients will work similar to the MCP +# config commands. +$ tsh mcp gateway install --client-config=claude +$ tsh mcp gateway install --client-config=vscode + +# Listing the available MCPs will still be done by the current commands +# `tsh mcp ls` and `tsh db ls`. + +# Managing servers will have no different commands for apps and databases. +$ tsh mcp gateway add mcp-everything +$ tsh mcp gateway add pg-dev --db-user=readonly --db-name=postgres + +$ tsh mcp gateway rm mcp-everything +$ tsh mcp gateway rm pg-dev +``` + +## Details + +WIP diff --git a/rfd/assets/0221-configure-clients-dialog.png b/rfd/assets/0221-configure-clients-dialog.png new file mode 100644 index 0000000000000..41d91eb15433c Binary files /dev/null and b/rfd/assets/0221-configure-clients-dialog.png differ diff --git a/rfd/assets/0221-connections-with-missing-client.png b/rfd/assets/0221-connections-with-missing-client.png new file mode 100644 index 0000000000000..561480302350d Binary files /dev/null and b/rfd/assets/0221-connections-with-missing-client.png differ diff --git a/rfd/assets/0221-connections-with-servers-errors.png b/rfd/assets/0221-connections-with-servers-errors.png new file mode 100644 index 0000000000000..ccc5512815447 Binary files /dev/null and b/rfd/assets/0221-connections-with-servers-errors.png differ diff --git a/rfd/assets/0221-connections-with-servers.png b/rfd/assets/0221-connections-with-servers.png new file mode 100644 index 0000000000000..94b75e3300604 Binary files /dev/null and b/rfd/assets/0221-connections-with-servers.png differ diff --git a/rfd/assets/0221-connections.png b/rfd/assets/0221-connections.png new file mode 100644 index 0000000000000..05917585b7452 Binary files /dev/null and b/rfd/assets/0221-connections.png differ diff --git a/rfd/assets/0221-resources-view-enabled.png b/rfd/assets/0221-resources-view-enabled.png new file mode 100644 index 0000000000000..939b99edbbc4e Binary files /dev/null and b/rfd/assets/0221-resources-view-enabled.png differ diff --git a/rfd/assets/0221-resources-view.png b/rfd/assets/0221-resources-view.png new file mode 100644 index 0000000000000..10eb96103d77f Binary files /dev/null and b/rfd/assets/0221-resources-view.png differ