MCP Access Reference

Report an issue with this page

This guide describes interfaces and options for interacting with the Teleport Application Service for MCP access, including the static configuration file for the teleport binary, and tsh mcp commands.

Configuration

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

The following snippet shows the full YAML configuration of an Application Service appearing in the teleport.yaml configuration file:

app_service:
  # Enables application proxy service.
  enabled: true
  # Enables the builtin Teleport demo MCP server that shows current user and
  # session information. To access it, this MCP server uses the app label
  # "teleport.internal/resource-type" with the value "demo".
  mcp_demo_server: true
  # This section contains definitions of all applications proxied by this
  # service. It can contain multiple items.
  apps:
  # Name of the application. Used for identification purposes.
  - name: "mcp-everything"
    # Endpoint URI of the target MCP server.
    # Use "mcp+http://" and "mcp+https://" as scheme for streamable HTTP MCP servers.
    # Use "mcp+sse+http://" and "mcp+sse+https://" as scheme for SSE MCP servers.
    # Leave it empty or use "mcp+stdio://" for stdio MCP servers.
    uri: "mcp+http://localhost:12345/mcp"
    # Free-form application description.
    description: "Example Everything MCP server"
    # Static labels to assign to the app. Used in RBAC.
    labels:
      env: "prod"

    # Contains MCP server-related configurations.
    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"

    # Disable TLS validation for SSE and streamable HTTP MCP servers.
    insecure_skip_verify: true
    # Rewrites section for SSE and streamable HTTP MCP servers.
    rewrite:
      # Specify whether to include roles or traits in the JWT.
      # Options:
      # - roles-and-traits: include both roles and traits
      # - roles: include only roles
      # - traits: include only traits
      # - none: exclude both roles and traits from the JWT token
      # Default: roles-and-traits
      jwt_claims: roles-and-traits
      # Headers passthrough configuration.
      headers:
      - "Authorization: Bearer {{internal.jwt}}"
      - "X-Custom-Header: example"
      - "X-External-Trait: {{external.env}}"

Resource

The MCP server resources are registered as app resources in the Teleport backend. Here is the spec of MCP server resources managed by tctl resource command:

kind: app
version: v3
metadata:
  # MCP server name
  name: everything
  # MCP server description.
  description: The Everything MCP server
  # MCP server labels.
  labels:
    env: local
spec:
  # Endpoint URI of the target MCP server.
  # Use "mcp+http://" and "mcp+https://" as scheme for streamable HTTP MCP servers.
  # Use "mcp+sse+http://" and "mcp+sse+https://" as scheme for SSE MCP servers.
  # Leave it empty or use "mcp+stdio://" for stdio MCP servers.
  uri: "mcp+http://localhost:12345/mcp"

  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"

  # Disable TLS validation for SSE and streamable HTTP MCP servers.
  insecure_skip_verify: true
  # Rewrites section for SSE and streamable HTTP MCP servers.
  rewrite:
    # Specify whether to include roles or traits in the JWT.
    # Options:
    # - roles-and-traits: include both roles and traits
    # - roles: include only roles
    # - traits: include only traits
    # - none: exclude both roles and traits from the JWT token
    # Default: roles-and-traits
    jwt_claims: roles-and-traits
    # Headers passthrough configuration.
    headers:
    - "Authorization: Bearer {{internal.jwt}}"
    - "X-Custom-Header: example"
    - "X-External-Trait: {{external.env}}"

CLI

This section shows CLI commands relevant for MCP access.

tsh mcp ls

Lists available MCP servers.

List all MCP servers.
tsh mcp ls
Search MCP servers with keywords.
tsh mcp ls --search foo,bar
Filter MCP servers with labels.
tsh mcp ls key1=value1,key2=value2
Get MCP server names using "jq".
tsh mcp ls --format json  | jq -r '.[].metadata.name'

Flag	Description
--search	List of comma separated search keywords or phrases enclosed in quotations (e.g. --search=foo,bar,"some phrase").
--query	Query by predicate language enclosed in single quotes. (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--format	Format output (text, json, yaml).

tsh mcp config

Print client configuration details or update the configuration directly.

Print sample configuration for a MCP server app
tsh mcp config my-mcp-server-app
Print sample configuration for a streamable HTTP MCP server with custom headers
tsh mcp config my-mcp-server-app -H "Header1: value1" -H "Header2: value2"
Add all MCP servers to Claude Desktop
tsh mcp config --all --client-config=claude
Search MCP servers with labels and add to the specified JSON file
tsh mcp config --labels env=dev --client-config=my-config.json`

Flag	Description
--all	Select all MCP servers. Mutually exclusive with --labels or --query.
--labels	List of comma separated labels to filter by labels (e.g. key1=value1,key2=value2).
--query	Query by predicate language enclosed in single quotes. (e.g. --query='labels["key1"] == "value1" && labels["key2"] != "value2"').
--client-config	If specified, update the specified client config. claude for default Claude Desktop config, or specify a JSON file path. Can also be set with environment variable TELEPORT_MCP_CLIENT_CONFIG.",
--json-format	Format the JSON file (pretty, compact, auto, none). auto saves in compact if the file is already compact, otherwise pretty. Can also be set with environment variable TELEPORT_MCP_CONFIG_JSON_FORMAT. Default is auto.",
-H, --header	Extra custom headers used for streamable HTTP MCP servers.

tsh mcp connect

Used by AI tools such as Claude Desktop to connect to an MCP server via Teleport.

tip

tsh mcp config can print sample configuration or update your AI tools directly. This eliminates the need to manually construct the tsh mcp connect command.

tsh mcp connect mcp-everything

tsh debug logs are enabled by default and can be disabled by the environment variable TELEPORT_DEBUG=false. You can also specify the --no-debug flag when generating sample configurations with tsh mcp config.

tsh proxy mcp

Starts a local proxy for MCP connections. Only supported for target MCP servers with streamable HTTP transport.

tsh proxy mcp my-streamable-http-mcp-server