Skip to main content
Version: 18.x

Dynamic MCP Server Registration

Report an issue with this page

Dynamic MCP server registration allows Teleport administrators to register new MCP servers (or update/unregister existing ones) without having to update the static configuration files read by Teleport Application Service instances.

The MCP server resources are registered as app resources in the Teleport backend. Application Service instances periodically query the Teleport Auth Service for app resources, each of which includes the information that the Application Service needs to proxy an application.

Required permissions​

In order to interact with dynamically registered applications, a user must have a Teleport role with permissions to manage app resources.

In the following example, a role allows a user to perform all possible operations against app resources:

allow:
  rules:
    - resources:
        - app
      verbs: [list, create, read, update, delete]

Enabling dynamic registration​

To enable dynamic registration, include a resources section in your Application Service configuration with a list of resource label selectors you'd like this service to monitor for registering:

app_service:
  enabled: true
  resources:
  - labels:
      "*": "*"

You can use a wildcard selector to register all dynamic app resources in the cluster on the Application Service or provide a specific set of labels for a subset:

resources:
- labels:
    "env": "prod"
- labels:
    "env": "test"

Creating a MCP server​

The following example configures Teleport to proxy the "Everything" MCP server by launching it through docker:

kind: app
version: v3
metadata:
  name: everything
  description: The Everything MCP server
  labels:
    env: dev
spec:
  mcp:
    # Command to launch stdio-based MCP servers.
    command: "docker"
    # Args to execute with the command.
    args: ["run", "-i", "--rm", "mcp/everything"]
    # Name of the host user account under which the command will be
    # executed. Required for stdio-based MCP servers.
    run_as_host_user: "docker"

See the full resource spec reference.

To create the resource, run:

Log in to your cluster with tsh so you can use tctl from your local machine.
You can also run tctl on your Auth Service host without running "tsh login"
first.
tsh login --proxy=teleport.example.com --user=myuser
tctl create mcp_server.yaml

After the resource has been created, it will appear among the list of available MCP servers (in tsh mcp ls or UI) as long as at least one Application Service instance picks it up according to its label selectors.

To update an existing application resource, run:

tctl create -f mcp_server.yaml

If the updated resource's labels no longer match a particular app agent, it will unregister and stop proxying it.

To delete the resource, run:

tctl rm app/everything