Document MCP tool filter naming across SDKs

dotnet/README.md

@@ -64,6 +64,12 @@ await session.SendAsync(new MessageOptions { Prompt = "What is 2+2?" });
 await done.Task;
 ```
 
+When targeting MCP tools configured through `McpServers`, remember the runtime
+tool name is `<server-key>-<tool-name>`. For `AvailableTools` and
+`ExcludedTools`, prefer the source-qualified form
+`mcp:<server-key>-<tool-name>`. For `CustomAgents[].Tools` and
+`DefaultAgent.ExcludedTools`, use `<server-key>-<tool-name>` directly.
+
 ## API Reference
 
 ### CopilotClient

dotnet/src/Types.cs

@@ -2604,6 +2604,8 @@ public sealed class CustomAgentConfig
 
     /// <summary>
     /// List of tool names the agent can use. Null for all tools.
+    /// For MCP tools from <see cref="SessionConfigBase.McpServers"/>, use the
+    /// runtime tool name <c>&lt;server-key&gt;-&lt;tool-name&gt;</c>.
     /// </summary>
     [JsonPropertyName("tools")]
     public IList<string>? Tools { get; set; }
@@ -2655,7 +2657,9 @@ public sealed class DefaultAgentConfig
     /// <summary>
     /// List of tool names to exclude from the default agent.
     /// These tools remain available to custom sub-agents that reference them
-    /// in their <see cref="CustomAgentConfig.Tools"/> list.
+    /// in their <see cref="CustomAgentConfig.Tools"/> list. For MCP tools from
+    /// <see cref="SessionConfigBase.McpServers"/>, use
+    /// <c>&lt;server-key&gt;-&lt;tool-name&gt;</c>.
     /// </summary>
     public IList<string>? ExcludedTools { get; set; }
 }
@@ -3008,10 +3012,19 @@ protected SessionConfigBase(SessionConfigBase? other)
     /// <summary>System message configuration for the session.</summary>
     public SystemMessageConfig? SystemMessage { get; set; }
 
-    /// <summary>List of tool names to allow; only these tools will be available when specified.</summary>
+    /// <summary>
+    /// List of tool names to allow; only these tools will be available when specified.
+    /// For MCP tools from <see cref="McpServers"/>, the runtime tool name is
+    /// <c>&lt;server-key&gt;-&lt;tool-name&gt;</c>; prefer the source-qualified
+    /// filter form <c>mcp:&lt;server-key&gt;-&lt;tool-name&gt;</c>.
+    /// </summary>
     public IList<string>? AvailableTools { get; set; }
 
-    /// <summary>List of tool names to exclude from the session.</summary>
+    /// <summary>
+    /// List of tool names to exclude from the session.
+    /// Use the same MCP naming convention as <see cref="AvailableTools"/> when
+    /// targeting tools from <see cref="McpServers"/>.
+    /// </summary>
     public IList<string>? ExcludedTools { get; set; }
 
     /// <summary>
@@ -3174,13 +3187,19 @@ protected SessionConfigBase(SessionConfigBase? other)
     /// </summary>
     public McpOAuthTokenStorageMode? McpOAuthTokenStorage { get; set; }
 
-    /// <summary>Custom agent configurations for the session.</summary>
+    /// <summary>
+    /// Custom agent configurations for the session.
+    /// When an agent <see cref="CustomAgentConfig.Tools"/> list targets an MCP
+    /// tool from <see cref="McpServers"/>, use
+    /// <c>&lt;server-key&gt;-&lt;tool-name&gt;</c>.
+    /// </summary>
     public IList<CustomAgentConfig>? CustomAgents { get; set; }
 
     /// <summary>
     /// Configuration for the default agent (the built-in agent that handles turns when no custom agent is selected).
     /// Use <see cref="DefaultAgentConfig.ExcludedTools"/> to hide specific tools from the default agent
-    /// while keeping them available to custom sub-agents.
+    /// while keeping them available to custom sub-agents. For MCP tools from
+    /// <see cref="McpServers"/>, use <c>&lt;server-key&gt;-&lt;tool-name&gt;</c>.
     /// </summary>
     public DefaultAgentConfig? DefaultAgent { get; set; }
 

go/README.md

@@ -89,6 +89,12 @@ func main() {
 }
 ```
 
+When targeting MCP tools configured through `MCPServers`, remember the runtime
+tool name is `<server-key>-<tool-name>`. For `AvailableTools` and
+`ExcludedTools`, prefer the source-qualified form
+`mcp:<server-key>-<tool-name>`. For `CustomAgents[].Tools` and
+`DefaultAgent.ExcludedTools`, use `<server-key>-<tool-name>` directly.
+
 ## Distributing your application with an embedded GitHub Copilot CLI
 
 The SDK supports bundling, using Go's `embed` package, the Copilot CLI binary within your application's distribution.

go/types.go

@@ -888,7 +888,9 @@ type CustomAgentConfig struct {
 	// Description of what the agent does
 	Description string `json:"description,omitempty"`
 	// Tools is the list of tool names the agent can use. Nil omits the field
-	// (all tools); an empty non-nil slice sends "tools": [] (no tools).
+	// (all tools); an empty non-nil slice sends "tools": [] (no tools). For
+	// MCP tools from MCPServers, use the runtime tool name
+	// <server-key>-<tool-name>.
 	Tools []string `json:"tools,omitzero"`
 	// Prompt is the prompt content for the agent
 	Prompt string `json:"prompt"`
@@ -909,7 +911,9 @@ type CustomAgentConfig struct {
 // them available to custom sub-agents.
 type DefaultAgentConfig struct {
 	// ExcludedTools is a list of tool names to exclude from the default agent.
-	// These tools remain available to custom sub-agents that reference them in their Tools list.
+	// These tools remain available to custom sub-agents that reference them in
+	// their Tools list. For MCP tools from MCPServers, use
+	// <server-key>-<tool-name>.
 	ExcludedTools []string `json:"excludedTools,omitempty"`
 }
 
@@ -1034,11 +1038,15 @@ type SessionConfig struct {
 	Tools []Tool
 	// SystemMessage configures system message customization
 	SystemMessage *SystemMessageConfig
-	// AvailableTools is a list of tool names to allow. When specified, only these tools will be available.
-	// Takes precedence over ExcludedTools.
+	// AvailableTools is a list of tool names to allow. When specified, only
+	// these tools will be available. Takes precedence over ExcludedTools. For
+	// MCP tools from MCPServers, the runtime tool name is
+	// <server-key>-<tool-name>; prefer the source-qualified filter form
+	// mcp:<server-key>-<tool-name>.
 	AvailableTools []string
-	// ExcludedTools is a list of tool names to disable. All other tools remain available.
-	// Ignored if AvailableTools is specified.
+	// ExcludedTools is a list of tool names to disable. All other tools remain
+	// available. Ignored if AvailableTools is specified. Use the same MCP naming
+	// convention as AvailableTools when targeting tools from MCPServers.
 	ExcludedTools []string
 	// ExcludedBuiltInAgents is a list of built-in agent names to exclude from
 	// the session. Excluded built-in agents are hidden from discovery and cannot
@@ -1126,10 +1134,14 @@ type SessionConfig struct {
 	// MCPOAuthTokenStorage controls how MCP OAuth tokens are stored for this session.
 	// When empty, the runtime default ("in-memory") is used.
 	MCPOAuthTokenStorage string
-	// CustomAgents configures custom agents for the session
+	// CustomAgents configures custom agents for the session. When an agent Tools
+	// list targets an MCP tool from MCPServers, use
+	// <server-key>-<tool-name>.
 	CustomAgents []CustomAgentConfig
-	// DefaultAgent configures the default agent (the built-in agent that handles turns when no custom agent is selected).
-	// Use ExcludedTools to hide tools from the default agent while keeping them available to sub-agents.
+	// DefaultAgent configures the default agent (the built-in agent that handles
+	// turns when no custom agent is selected). Use ExcludedTools to hide tools
+	// from the default agent while keeping them available to sub-agents. For MCP
+	// tools from MCPServers, use <server-key>-<tool-name> in ExcludedTools.
 	DefaultAgent *DefaultAgentConfig
 	// Agent is the name of the custom agent to activate when the session starts.
 	// Must match the Name of one of the agents in CustomAgents.
@@ -1441,11 +1453,15 @@ type ResumeSessionConfig struct {
 	Tools []Tool
 	// SystemMessage configures system message customization
 	SystemMessage *SystemMessageConfig
-	// AvailableTools is a list of tool names to allow. When specified, only these tools will be available.
-	// Takes precedence over ExcludedTools.
+	// AvailableTools is a list of tool names to allow. When specified, only
+	// these tools will be available. Takes precedence over ExcludedTools. For
+	// MCP tools from MCPServers, the runtime tool name is
+	// <server-key>-<tool-name>; prefer the source-qualified filter form
+	// mcp:<server-key>-<tool-name>.
 	AvailableTools []string
-	// ExcludedTools is a list of tool names to disable. All other tools remain available.
-	// Ignored if AvailableTools is specified.
+	// ExcludedTools is a list of tool names to disable. All other tools remain
+	// available. Ignored if AvailableTools is specified. Use the same MCP naming
+	// convention as AvailableTools when targeting tools from MCPServers.
 	ExcludedTools []string
 	// ExcludedBuiltInAgents is a list of built-in agent names to exclude from
 	// the session. Excluded built-in agents are hidden from discovery and cannot
@@ -1577,9 +1593,13 @@ type ResumeSessionConfig struct {
 	// MCPOAuthTokenStorage controls how MCP OAuth tokens are stored for this session.
 	// When empty, the runtime default ("in-memory") is used.
 	MCPOAuthTokenStorage string
-	// CustomAgents configures custom agents for the session
+	// CustomAgents configures custom agents for the session. When an agent Tools
+	// list targets an MCP tool from MCPServers, use
+	// <server-key>-<tool-name>.
 	CustomAgents []CustomAgentConfig
-	// DefaultAgent configures the default agent (the built-in agent that handles turns when no custom agent is selected).
+	// DefaultAgent configures the default agent (the built-in agent that handles
+	// turns when no custom agent is selected). For MCP tools from MCPServers,
+	// use <server-key>-<tool-name> in ExcludedTools.
 	DefaultAgent *DefaultAgentConfig
 	// Agent is the name of the custom agent to activate when the session starts.
 	// Must match the Name of one of the agents in CustomAgents.

java/README.md

@@ -120,6 +120,13 @@ public class CopilotSDK {
 }
 ```
 
+When targeting MCP tools configured through `setMcpServers(...)`, remember the
+runtime tool name is `<server-key>-<tool-name>`. For `setAvailableTools(...)`
+and `setExcludedTools(...)`, prefer the source-qualified filter form
+`mcp:<server-key>-<tool-name>`. For `CustomAgentConfig.setTools(...)` and
+`DefaultAgentConfig.setExcludedTools(...)`, use `<server-key>-<tool-name>`
+directly.
+
 ## Try it with JBang
 
 You can run the SDK without setting up a full Java project, by using [JBang](https://www.jbang.dev/).

java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java

@@ -144,7 +144,9 @@ public List<String> getTools() {
      * Sets the tools available to this agent.
      * <p>
      * These can reference both built-in tools and custom tools registered in the
-     * session.
+     * session. For MCP tools from {@link SessionConfig#setMcpServers(Map)} or
+     * {@link ResumeSessionConfig#setMcpServers(Map)}, use the runtime tool name
+     * {@code <server-key>-<tool-name>}.
      *
      * @param tools
      *            the list of tool names

java/src/main/java/com/github/copilot/rpc/DefaultAgentConfig.java

@@ -46,7 +46,10 @@ public List<String> getExcludedTools() {
      * Sets the list of tool names to exclude from the default agent.
      * <p>
      * These tools remain available to custom sub-agents that reference them in
-     * their {@link CustomAgentConfig#setTools(List)} list.
+     * their {@link CustomAgentConfig#setTools(List)} list. For MCP tools from
+     * {@link SessionConfig#setMcpServers(Map)} or
+     * {@link ResumeSessionConfig#setMcpServers(Map)}, use the runtime tool name
+     * {@code <server-key>-<tool-name>}.
      *
      * @param excludedTools
      *            the list of tool names to exclude from the default agent

java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java

@@ -209,7 +209,10 @@ public List<String> getAvailableTools() {
      * Sets the list of tool names that are allowed in this session.
      * <p>
      * When specified, only tools in this list will be available to the assistant.
-     * Takes precedence over excluded tools.
+     * Takes precedence over excluded tools. MCP tools from
+     * {@link #setMcpServers(Map)} use the runtime name
+     * {@code <server-key>-<tool-name>}; prefer the source-qualified filter form
+     * {@code mcp:<server-key>-<tool-name>}.
      *
      * @param availableTools
      *            the list of allowed tool names
@@ -233,7 +236,9 @@ public List<String> getExcludedTools() {
      * Sets the list of tool names to exclude from this session.
      * <p>
      * Tools in this list will not be available to the assistant. Ignored if
-     * available tools is specified.
+     * available tools is specified. Use the same MCP naming convention as
+     * {@link #setAvailableTools(List)} when targeting tools from
+     * {@link #setMcpServers(Map)}.
      *
      * @param excludedTools
      *            the list of tool names to exclude
@@ -1304,6 +1309,10 @@ public List<CustomAgentConfig> getCustomAgents() {
 
     /**
      * Sets custom agent configurations.
+     * <p>
+     * When an agent {@link CustomAgentConfig#setTools(List)} list targets an
+     * MCP tool from {@link #setMcpServers(Map)}, use the runtime tool name
+     * {@code <server-key>-<tool-name>}.
      *
      * @param customAgents
      *            the list of custom agent configurations
@@ -1329,6 +1338,8 @@ public DefaultAgentConfig getDefaultAgent() {
      * <p>
      * Use {@link DefaultAgentConfig#setExcludedTools(List)} to hide specific tools
      * from the default agent while keeping them available to custom sub-agents.
+     * MCP tools from {@link #setMcpServers(Map)} use the runtime tool name
+     * {@code <server-key>-<tool-name>}.
      *
      * @param defaultAgent
      *            the default agent configuration

java/src/main/java/com/github/copilot/rpc/SessionConfig.java

@@ -309,6 +309,9 @@ public List<String> getAvailableTools() {
      * Sets the list of tool names that are allowed in this session.
      * <p>
      * When specified, only tools in this list will be available to the assistant.
+     * MCP tools from {@link #setMcpServers(Map)} use the runtime name
+     * {@code <server-key>-<tool-name>}; prefer the source-qualified filter form
+     * {@code mcp:<server-key>-<tool-name>}.
      *
      * @param availableTools
      *            the list of allowed tool names
@@ -331,7 +334,9 @@ public List<String> getExcludedTools() {
     /**
      * Sets the list of tool names to exclude from this session.
      * <p>
-     * Tools in this list will not be available to the assistant.
+     * Tools in this list will not be available to the assistant. Use the same
+     * MCP naming convention as {@link #setAvailableTools(List)} when targeting
+     * tools from {@link #setMcpServers(Map)}.
      *
      * @param excludedTools
      *            the list of tool names to exclude
@@ -955,7 +960,9 @@ public List<CustomAgentConfig> getCustomAgents() {
      * Sets custom agent configurations.
      * <p>
      * Custom agents allow extending the assistant with specialized behaviors and
-     * capabilities.
+     * capabilities. When an agent {@link CustomAgentConfig#setTools(List)} list
+     * targets an MCP tool from {@link #setMcpServers(Map)}, use the runtime
+     * tool name {@code <server-key>-<tool-name>}.
      *
      * @param customAgents
      *            the list of custom agent configurations
@@ -981,6 +988,8 @@ public DefaultAgentConfig getDefaultAgent() {
      * <p>
      * Use {@link DefaultAgentConfig#setExcludedTools(List)} to hide specific tools
      * from the default agent while keeping them available to custom sub-agents.
+     * MCP tools from {@link #setMcpServers(Map)} use the runtime tool name
+     * {@code <server-key>-<tool-name>}.
      *
      * @param defaultAgent
      *            the default agent configuration

nodejs/README.md

@@ -71,6 +71,12 @@ await using session = await client.createSession({
 // session is automatically disconnected when leaving scope
 ```
 
+When targeting MCP tools configured through `mcpServers`, remember the runtime
+tool name is `<server-key>-<tool-name>`. For `availableTools` and
+`excludedTools`, prefer `new ToolSet().addMcp("<server-key>-<tool-name>")` or
+the raw `mcp:<server-key>-<tool-name>` form. For `customAgents[].tools` and
+`defaultAgent.excludedTools`, use `<server-key>-<tool-name>` directly.
+
 ## API Reference
 
 ### CopilotClient

nodejs/src/types.ts

@@ -1512,7 +1512,8 @@ export interface CustomAgentConfig {
     description?: string;
     /**
      * List of tool names the agent can use.
-     * Use null or undefined for all tools.
+     * Use null or undefined for all tools. For MCP tools from `mcpServers`,
+     * use the runtime tool name `<server-key>-<tool-name>`.
      */
     tools?: string[] | null;
     /**
@@ -1877,7 +1878,10 @@ export interface SessionConfigBase {
      * Supports source-qualified filter patterns (`builtin:*`, `builtin:<name>`,
      * `mcp:*`, `mcp:<name>`, `custom:*`, `custom:<name>`) as well as the bare
      * name form (exact match across any source). Build this list with
-     * {@link ToolSet} for type safety and readable intent.
+     * {@link ToolSet} for type safety and readable intent. For MCP tools from
+     * `mcpServers`, the runtime tool name is `<server-key>-<tool-name>`, so
+     * prefer `new ToolSet().addMcp("<server-key>-<tool-name>")` or the raw
+     * `mcp:<server-key>-<tool-name>` form.
      *
      * Composes with {@link excludedTools}: a tool is enabled when it matches
      * `availableTools` (or `availableTools` is unset) AND it does not match
@@ -1887,7 +1891,8 @@ export interface SessionConfigBase {
 
     /**
      * List of tool names to disable. Supports the same pattern syntax as
-     * {@link availableTools}.
+     * {@link availableTools}. Use the same MCP naming convention when targeting
+     * tools from `mcpServers`.
      *
      * Always takes precedence over {@link availableTools}: a tool listed here
      * is disabled even if it also matches `availableTools`.
@@ -2117,14 +2122,17 @@ export interface SessionConfigBase {
 
     /**
      * Custom agent configurations for the session.
+     * When an agent `tools` list targets an MCP tool from `mcpServers`, use
+     * `<server-key>-<tool-name>`.
      */
     customAgents?: CustomAgentConfig[];
 
     /**
      * Configuration for the default agent (the built-in agent that handles
      * turns when no custom agent is selected).
      * Use `excludedTools` to hide specific tools from the default agent while keeping
-     * them available to custom sub-agents.
+     * them available to custom sub-agents. For MCP tools from `mcpServers`,
+     * use `<server-key>-<tool-name>`.
      */
     defaultAgent?: DefaultAgentConfig;
 

python/README.md

@@ -220,6 +220,7 @@ These are passed as keyword arguments to `create_session()`:
 - `on_permission_request` (callable): Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `PermissionHandler.approve_all` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
 - `on_user_input_request` (callable): Handler for user input requests from the agent (enables ask_user tool). See [User Input Requests](#user-input-requests) section.
 - `hooks` (SessionHooks): Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
+- `available_tools` / `excluded_tools` / `default_agent.excluded_tools` / custom-agent `tools`: MCP tools registered from `mcp_servers` are exposed to the runtime as `<server-key>-<tool-name>`. For `available_tools` and `excluded_tools`, prefer `ToolSet().add_mcp("<server-key>-<tool-name>")` or the raw `mcp:<server-key>-<tool-name>` form. For custom-agent `tools` and `default_agent.excluded_tools`, use `<server-key>-<tool-name>` directly.
 
 **Session Lifecycle Methods:**