Enable the MCP server
Enable Retool's MCP server on a self-hosted instance so MCP clients can connect and authenticate with OAuth 2.0.
Retool's MCP server lets compatible MCP clients connect to your self-hosted instance over HTTPS and authenticate with OAuth 2.0. On self-hosted instances, the MCP server runs as a separate service that you enable and route to at https://example.retool.com/mcp.
This guide explains how to enable the MCP service, route public traffic to it, and verify the connection. Once you're done, refer to Use Retool's MCP server to learn how to connect a client and which tools are available.
Requirements
Before you enable the MCP server, make sure you have:
- Retool 4.0.0 or later. If you're setting up a new instance, complete the self-hosted quickstart first. If you're upgrading your instance, follow the upgrade guide that applies to you.
- To use the app-generation tools, the new app builder's supporting services: the agent sandbox, Temporal, and a code executor or JS executor. For setup steps, refer to Update Helm configuration. MCP can connect and serve its other tools without these services, but the app-generation tools don't appear in your MCP client's tool list until they're running.
- A public HTTPS origin for Retool, which this guide refers to as
https://example.retool.com. The MCP endpoint and the OAuth endpoints must use this same origin. - Access to change your public routes, whether the Retool Helm chart or your own ingress, gateway, or load balancer manages them.
Kubernetes with Helm is the supported production deployment method for Retool 4.0 and later. Other methods are suitable only for development and testing.
MCP traffic routing
The MCP server runs as its own service. MCP clients connect to /mcp and discover OAuth settings through /.well-known metadata paths. The MCP service serves /mcp and protected-resource metadata. The main Retool backend serves authorization-server metadata and the OAuth API endpoints. All of these are presented under your existing public Retool origin. To configure these routes, refer to Configure public routes. If an SSO gateway protects your origin, also refer to Configure an SSO gateway.
The MCP service also needs a private connection to the Retool backend so it can validate tokens and run tools. Keep this connection on your internal network and keep the MCP service port private.
Enable the MCP service
Complete the following steps to enable the MCP service on your instance.
- Helm
- Non-Helm
Set the public origin
In the values file for your existing Retool instance, enable the MCP service and set the public origin.
mcp:
enabled: true
routing:
mode: direct
config:
mcpServiceExternalUrl: "https://example.retool.com"
direct is the chart's default routing mode. It adds dedicated public routes for the MCP service. For more information, refer to Configure public routes.
Three addresses are involved in an MCP connection:
| Address | Purpose | Helm setting |
|---|---|---|
| Public URL | The origin that users visit and MCP clients connect to. Clients use this URL followed by /mcp. The MCP service also uses it to build the URL that clients upload app imports to. It must not include /mcp. | mcp.config.mcpServiceExternalUrl |
| OAuth hostname | The public Retool hostname that serves OAuth metadata and the /api/oauth2/* endpoints. It's a hostname only, without https://. | mcp.config.oauthMainDomain. Defaults to the plain-text value of env.BASE_DOMAIN. Set this yourself if BASE_DOMAIN comes from a Kubernetes Secret or isn't set. |
| Private backend URL | The internal address the MCP service uses to reach the Retool backend, so it can validate tokens and run tools. | mcp.config.retoolBackendUrl. The chart sets this automatically. |
For example, if users visit https://retool.example.com, the three addresses are:
- Public URL:
https://retool.example.com - OAuth hostname:
retool.example.com - Client endpoint:
https://retool.example.com/mcp
Set secrets
When an MCP client sends a request, the MCP service asks the Retool backend to check the user's access token. The backend and MCP workloads must receive the same introspection token. This token is a secret that only the backend and the MCP service share. It's separate from the access token a client receives after the user signs in.
Let the chart manage the token
When the chart manages your configuration secrets and you don't set a secret name, it generates the token and gives the same value to the backend and MCP workloads. You don't need to do anything.
Manage the token yourself
If you manage secrets separately, store the token in a Kubernetes Secret. The following example creates the secret with a random value:
kubectl create secret generic retool-mcp-oauth \
--from-literal=oauthIntrospectionAuthToken="$(openssl rand -hex 32)"
Then set the secret's name in your values file:
mcp:
config:
oauthIntrospectionAuthTokenSecretName: retool-mcp-oauth
The chart reads the token from this secret and sets it as OAUTH_INTROSPECTION_AUTH_TOKEN on both the backend and MCP workloads, so both receive the same value. If the key in your secret isn't oauthIntrospectionAuthToken, also set mcp.config.oauthIntrospectionAuthTokenSecretKey.
If you set OAUTH_INTROSPECTION_AUTH_TOKEN through mcp.environmentVariables instead, set the same value for the backend through the top-level env, environmentVariables, or environmentSecrets values.
For the full list of settings, refer to the MCP values in the Retool Helm chart.