# MCP Access Reference 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 ```