diff --git a/dotnet/README.md b/dotnet/README.md index 796ef22549..83398aff2c 100644 --- a/dotnet/README.md +++ b/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 `-`. For `AvailableTools` and +`ExcludedTools`, prefer the source-qualified form +`mcp:-`. For `CustomAgents[].Tools` and +`DefaultAgent.ExcludedTools`, use `-` directly. + ## API Reference ### CopilotClient diff --git a/dotnet/src/Types.cs b/dotnet/src/Types.cs index 63e39a2c56..b4e4af5463 100644 --- a/dotnet/src/Types.cs +++ b/dotnet/src/Types.cs @@ -2604,6 +2604,8 @@ public sealed class CustomAgentConfig /// /// List of tool names the agent can use. Null for all tools. + /// For MCP tools from , use the + /// runtime tool name <server-key>-<tool-name>. /// [JsonPropertyName("tools")] public IList? Tools { get; set; } @@ -2655,7 +2657,9 @@ public sealed class DefaultAgentConfig /// /// List of tool names to exclude from the default agent. /// These tools remain available to custom sub-agents that reference them - /// in their list. + /// in their list. For MCP tools from + /// , use + /// <server-key>-<tool-name>. /// public IList? ExcludedTools { get; set; } } @@ -3008,10 +3012,19 @@ protected SessionConfigBase(SessionConfigBase? other) /// System message configuration for the session. public SystemMessageConfig? SystemMessage { get; set; } - /// List of tool names to allow; only these tools will be available when specified. + /// + /// List of tool names to allow; only these tools will be available when specified. + /// For MCP tools from , the runtime tool name is + /// <server-key>-<tool-name>; prefer the source-qualified + /// filter form mcp:<server-key>-<tool-name>. + /// public IList? AvailableTools { get; set; } - /// List of tool names to exclude from the session. + /// + /// List of tool names to exclude from the session. + /// Use the same MCP naming convention as when + /// targeting tools from . + /// public IList? ExcludedTools { get; set; } /// @@ -3174,13 +3187,19 @@ protected SessionConfigBase(SessionConfigBase? other) /// public McpOAuthTokenStorageMode? McpOAuthTokenStorage { get; set; } - /// Custom agent configurations for the session. + /// + /// Custom agent configurations for the session. + /// When an agent list targets an MCP + /// tool from , use + /// <server-key>-<tool-name>. + /// public IList? CustomAgents { get; set; } /// /// Configuration for the default agent (the built-in agent that handles turns when no custom agent is selected). /// Use 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 + /// , use <server-key>-<tool-name>. /// public DefaultAgentConfig? DefaultAgent { get; set; } diff --git a/go/README.md b/go/README.md index 5787e5a53e..f3f98572cc 100644 --- a/go/README.md +++ b/go/README.md @@ -89,6 +89,12 @@ func main() { } ``` +When targeting MCP tools configured through `MCPServers`, remember the runtime +tool name is `-`. For `AvailableTools` and +`ExcludedTools`, prefer the source-qualified form +`mcp:-`. For `CustomAgents[].Tools` and +`DefaultAgent.ExcludedTools`, use `-` 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. diff --git a/go/types.go b/go/types.go index 6111b7be41..07bf544143 100644 --- a/go/types.go +++ b/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 + // -. 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 + // -. 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 + // -; prefer the source-qualified filter form + // mcp:-. 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 + // -. 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 - 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 + // -; prefer the source-qualified filter form + // mcp:-. 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 + // -. 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 - 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. diff --git a/java/README.md b/java/README.md index 42e438e527..13e56123b8 100644 --- a/java/README.md +++ b/java/README.md @@ -120,6 +120,13 @@ public class CopilotSDK { } ``` +When targeting MCP tools configured through `setMcpServers(...)`, remember the +runtime tool name is `-`. For `setAvailableTools(...)` +and `setExcludedTools(...)`, prefer the source-qualified filter form +`mcp:-`. For `CustomAgentConfig.setTools(...)` and +`DefaultAgentConfig.setExcludedTools(...)`, use `-` +directly. + ## Try it with JBang You can run the SDK without setting up a full Java project, by using [JBang](https://www.jbang.dev/). diff --git a/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java b/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java index 5136f77786..991ef31625 100644 --- a/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java +++ b/java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java @@ -144,7 +144,9 @@ public List getTools() { * Sets the tools available to this agent. *

* 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 -}. * * @param tools * the list of tool names diff --git a/java/src/main/java/com/github/copilot/rpc/DefaultAgentConfig.java b/java/src/main/java/com/github/copilot/rpc/DefaultAgentConfig.java index 4be5dbbb9b..1e863b6d31 100644 --- a/java/src/main/java/com/github/copilot/rpc/DefaultAgentConfig.java +++ b/java/src/main/java/com/github/copilot/rpc/DefaultAgentConfig.java @@ -46,7 +46,10 @@ public List getExcludedTools() { * Sets the list of tool names to exclude from the default agent. *

* 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 -}. * * @param excludedTools * the list of tool names to exclude from the default agent diff --git a/java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java b/java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java index 0efe1c5c6a..ebdd5243a9 100644 --- a/java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java +++ b/java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java @@ -209,7 +209,10 @@ public List getAvailableTools() { * Sets the list of tool names that are allowed in this session. *

* 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 -}; prefer the source-qualified filter form + * {@code mcp:-}. * * @param availableTools * the list of allowed tool names @@ -233,7 +236,9 @@ public List getExcludedTools() { * Sets the list of tool names to exclude from this session. *

* 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 getCustomAgents() { /** * Sets custom agent configurations. + *

+ * When an agent {@link CustomAgentConfig#setTools(List)} list targets an + * MCP tool from {@link #setMcpServers(Map)}, use the runtime tool name + * {@code -}. * * @param customAgents * the list of custom agent configurations @@ -1329,6 +1338,8 @@ public DefaultAgentConfig getDefaultAgent() { *

* 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 -}. * * @param defaultAgent * the default agent configuration diff --git a/java/src/main/java/com/github/copilot/rpc/SessionConfig.java b/java/src/main/java/com/github/copilot/rpc/SessionConfig.java index 3533ceefac..d91615a443 100644 --- a/java/src/main/java/com/github/copilot/rpc/SessionConfig.java +++ b/java/src/main/java/com/github/copilot/rpc/SessionConfig.java @@ -309,6 +309,9 @@ public List getAvailableTools() { * Sets the list of tool names that are allowed in this session. *

* When specified, only tools in this list will be available to the assistant. + * MCP tools from {@link #setMcpServers(Map)} use the runtime name + * {@code -}; prefer the source-qualified filter form + * {@code mcp:-}. * * @param availableTools * the list of allowed tool names @@ -331,7 +334,9 @@ public List getExcludedTools() { /** * Sets the list of tool names to exclude from this session. *

- * 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 getCustomAgents() { * Sets custom agent configurations. *

* 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 -}. * * @param customAgents * the list of custom agent configurations @@ -981,6 +988,8 @@ public DefaultAgentConfig getDefaultAgent() { *

* 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 -}. * * @param defaultAgent * the default agent configuration diff --git a/nodejs/README.md b/nodejs/README.md index e9d83c6df9..7c050fdf8d 100644 --- a/nodejs/README.md +++ b/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 `-`. For `availableTools` and +`excludedTools`, prefer `new ToolSet().addMcp("-")` or +the raw `mcp:-` form. For `customAgents[].tools` and +`defaultAgent.excludedTools`, use `-` directly. + ## API Reference ### CopilotClient diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts index 65fc00cfe1..ad2714bc93 100644 --- a/nodejs/src/types.ts +++ b/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 `-`. */ tools?: string[] | null; /** @@ -1877,7 +1878,10 @@ export interface SessionConfigBase { * Supports source-qualified filter patterns (`builtin:*`, `builtin:`, * `mcp:*`, `mcp:`, `custom:*`, `custom:`) 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 `-`, so + * prefer `new ToolSet().addMcp("-")` or the raw + * `mcp:-` 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,6 +2122,8 @@ export interface SessionConfigBase { /** * Custom agent configurations for the session. + * When an agent `tools` list targets an MCP tool from `mcpServers`, use + * `-`. */ customAgents?: CustomAgentConfig[]; @@ -2124,7 +2131,8 @@ export interface SessionConfigBase { * 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 `-`. */ defaultAgent?: DefaultAgentConfig; diff --git a/python/README.md b/python/README.md index 86f568bd7a..669b8798d5 100644 --- a/python/README.md +++ b/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 `-`. For `available_tools` and `excluded_tools`, prefer `ToolSet().add_mcp("-")` or the raw `mcp:-` form. For custom-agent `tools` and `default_agent.excluded_tools`, use `-` directly. **Session Lifecycle Methods:** diff --git a/python/copilot/client.py b/python/copilot/client.py index dbe808bed2..86bf80f5cc 100644 --- a/python/copilot/client.py +++ b/python/copilot/client.py @@ -227,8 +227,6 @@ def _mcp_servers_to_wire( del config["working_directory"] wire[name] = config return wire - - def _large_output_to_wire(config: Mapping[str, Any]) -> dict[str, Any]: """Convert a ``LargeToolOutputConfig`` mapping to wire format.""" wire: dict[str, Any] = {} @@ -1784,10 +1782,15 @@ async def create_session( these tools will be available. Applies to the full merged tool catalog including built-in tools, MCP tools, and custom tools registered via ``tools=``. Custom tool names must be explicitly - included or they will be hidden from the model. Takes precedence - over ``excluded_tools``. + included or they will be hidden from the model. MCP tools from + ``mcp_servers`` are named ``-``; when + using source-qualified filters, prefer + ``ToolSet().add_mcp("-")`` or the raw + ``mcp:-`` form. Takes precedence over + ``excluded_tools``. excluded_tools: List of tools to disable. Applies to all tools - including custom tools registered via ``tools=``. Ignored if + including custom tools registered via ``tools=``. Use the same + MCP naming convention as ``available_tools``. Ignored if ``available_tools`` is set. on_user_input_request: Handler for user input requests. hooks: Lifecycle hooks for the session. @@ -1838,9 +1841,13 @@ async def create_session( `"persistent"` uses disk-based storage (shared across sessions). `"in-memory"` stores embeddings in memory (discarded on session end). Defaults to `"in-memory"` in empty mode. - custom_agents: Custom agent configurations. + custom_agents: Custom agent configurations. When an agent's + ``tools`` list targets an MCP tool from ``mcp_servers``, use + the runtime tool name ``-``. default_agent: Configuration for the default agent, - including tool visibility controls. + including tool visibility controls. When + ``default_agent.excluded_tools`` targets an MCP tool from + ``mcp_servers``, use ``-``. agent: Agent to use for the session. config_directory: Override for the configuration directory. enable_config_discovery: When True, automatically discovers MCP server @@ -2448,10 +2455,15 @@ async def resume_session( these tools will be available. Applies to the full merged tool catalog including built-in tools, MCP tools, and custom tools registered via ``tools=``. Custom tool names must be explicitly - included or they will be hidden from the model. Takes precedence - over ``excluded_tools``. + included or they will be hidden from the model. MCP tools from + ``mcp_servers`` are named ``-``; when + using source-qualified filters, prefer + ``ToolSet().add_mcp("-")`` or the raw + ``mcp:-`` form. Takes precedence over + ``excluded_tools``. excluded_tools: List of tools to disable. Applies to all tools - including custom tools registered via ``tools=``. Ignored if + including custom tools registered via ``tools=``. Use the same + MCP naming convention as ``available_tools``. Ignored if ``available_tools`` is set. on_user_input_request: Handler for user input requests. hooks: Lifecycle hooks for the session. @@ -2502,9 +2514,13 @@ async def resume_session( `"persistent"` uses disk-based storage (shared across sessions). `"in-memory"` stores embeddings in memory (discarded on session end). Defaults to `"in-memory"` in empty mode. - custom_agents: Custom agent configurations. + custom_agents: Custom agent configurations. When an agent's + ``tools`` list targets an MCP tool from ``mcp_servers``, use + the runtime tool name ``-``. default_agent: Configuration for the default agent, - including tool visibility controls. + including tool visibility controls. When + ``default_agent.excluded_tools`` targets an MCP tool from + ``mcp_servers``, use ``-``. agent: Agent to use for the session. config_directory: Override for the configuration directory. enable_config_discovery: When True, automatically discovers MCP server diff --git a/python/copilot/session.py b/python/copilot/session.py index 50de96f191..3bf30d7d85 100644 --- a/python/copilot/session.py +++ b/python/copilot/session.py @@ -1031,7 +1031,12 @@ class SessionHooks(TypedDict, total=False): class MCPStdioServerConfig(TypedDict, total=False): - """Configuration for a local/stdio MCP server.""" + """Configuration for a local/stdio MCP server. + + Tools exposed by the runtime are named ``-`` in + runtime-facing lists such as custom-agent ``tools`` and + ``default_agent.excluded_tools``. + """ tools: list[str] # List of tools to include. [] means none. "*" means all. type: NotRequired[Literal["local", "stdio"]] # Server type @@ -1043,7 +1048,12 @@ class MCPStdioServerConfig(TypedDict, total=False): class MCPHTTPServerConfig(TypedDict, total=False): - """Configuration for a remote MCP server (HTTP or SSE).""" + """Configuration for a remote MCP server (HTTP or SSE). + + Tools exposed by the runtime are named ``-`` in + runtime-facing lists such as custom-agent ``tools`` and + ``default_agent.excluded_tools``. + """ tools: list[str] # List of tools to include. [] means none. "*" means all. type: Literal["http", "sse"] # Server type @@ -1065,7 +1075,8 @@ class CustomAgentConfig(TypedDict, total=False): name: str # Unique name of the custom agent display_name: NotRequired[str] # Display name for UI purposes description: NotRequired[str] # Description of what the agent does - # List of tool names the agent can use + # List of tool names the agent can use. For MCP tools from ``mcp_servers``, + # use the runtime tool name ``-``. tools: NotRequired[list[str] | None] prompt: str # The prompt content for the agent # MCP servers specific to agent @@ -1084,8 +1095,9 @@ class DefaultAgentConfig(TypedDict, total=False): when no custom agent is selected. """ - # List of tool names to exclude from the default agent. - # These tools remain available to custom sub-agents that reference them. + # List of tool names to exclude from the default agent. For MCP tools from + # ``mcp_servers``, use ``-``. These tools remain + # available to custom sub-agents that reference them. excluded_tools: list[str] diff --git a/rust/README.md b/rust/README.md index 6d92224088..985d35b156 100644 --- a/rust/README.md +++ b/rust/README.md @@ -31,6 +31,12 @@ client.stop().await.ok(); # } ``` +When targeting MCP tools configured through `mcp_servers`, remember the runtime +tool name is `-`. For `available_tools` and +`excluded_tools`, prefer `ToolSet::new().add_mcp("-")` +or the raw `mcp:-` form. For `custom_agents[].tools` +and `default_agent.excluded_tools`, use `-` directly. + ## Architecture ```text diff --git a/rust/src/types.rs b/rust/src/types.rs index 6ccb43c854..d5b4a92aa7 100644 --- a/rust/src/types.rs +++ b/rust/src/types.rs @@ -608,6 +608,8 @@ pub struct CustomAgentConfig { #[serde(default, skip_serializing_if = "Option::is_none")] pub description: Option, /// List of tool names the agent can use. `None` means all tools. + /// For MCP tools from `mcp_servers`, use the runtime tool name + /// `-`. #[serde(default, skip_serializing_if = "Option::is_none")] pub tools: Option>, /// Prompt content for the agent. @@ -706,6 +708,7 @@ impl CustomAgentConfig { #[serde(rename_all = "camelCase")] pub struct DefaultAgentConfig { /// Tool names to exclude from the default agent. + /// For MCP tools from `mcp_servers`, use `-`. #[serde(default, skip_serializing_if = "Option::is_none")] pub excluded_tools: Option>, } @@ -1598,9 +1601,14 @@ pub struct SessionConfig { pub extension_sdk_path: Option, /// Stable extension identity for canvas/tool providers on this connection. pub extension_info: Option, - /// Allowlist of built-in tool names the agent may use. + /// Allowlist of tool names the agent may use. + /// For MCP tools from `mcp_servers`, the runtime tool name is + /// `-`; prefer the source-qualified filter form + /// `mcp:-`. pub available_tools: Option>, - /// Blocklist of built-in tool names the agent must not use. + /// Blocklist of tool names the agent must not use. + /// Use the same MCP naming convention as `available_tools` when targeting + /// tools from `mcp_servers`. pub excluded_tools: Option>, /// Names of built-in agents to exclude from the session. /// @@ -1682,10 +1690,13 @@ pub struct SessionConfig { /// submission, session start/end, errors). pub hooks: Option, /// Custom agents (sub-agents) configured for this session. + /// When an agent `tools` list targets an MCP tool from `mcp_servers`, use + /// `-`. pub custom_agents: Option>, /// Configures the built-in default agent. Use `excluded_tools` to /// hide tools from the default agent while keeping them available - /// to custom sub-agents that reference them in their `tools` list. + /// to custom sub-agents that reference them in their `tools` list. For + /// MCP tools from `mcp_servers`, use `-`. pub default_agent: Option, /// Name of the custom agent to activate when the session starts. /// Must match the `name` of one of the agents in [`Self::custom_agents`]. @@ -2803,8 +2814,13 @@ pub struct ResumeSessionConfig { /// Stable extension identity for canvas/tool providers on this connection. pub extension_info: Option, /// Allowlist of tool names the agent may use. + /// For MCP tools from `mcp_servers`, the runtime tool name is + /// `-`; prefer the source-qualified filter form + /// `mcp:-`. pub available_tools: Option>, - /// Blocklist of built-in tool names. + /// Blocklist of tool names. + /// Use the same MCP naming convention as `available_tools` when targeting + /// tools from `mcp_servers`. pub excluded_tools: Option>, /// Names of built-in agents to exclude from the resumed session. /// @@ -2855,8 +2871,12 @@ pub struct ResumeSessionConfig { /// Enable session hooks on resume. pub hooks: Option, /// Custom agents to re-supply on resume. + /// When an agent `tools` list targets an MCP tool from `mcp_servers`, use + /// `-`. pub custom_agents: Option>, /// Configures the built-in default agent on resume. + /// For MCP tools from `mcp_servers`, use `-` in + /// `excluded_tools`. pub default_agent: Option, /// Name of the custom agent to activate. pub agent: Option,