Documentation missing: MCP tools are prefixed with <server-key>- in available_tools / custom_agents[].tools

[ayushjai-ui]

Problem

When configuring mcp_servers in SessionConfig, the Copilot CLI backend registers discovered MCP tools with a prefixed name following the pattern <server-key>-<tool-name>. For example, a server keyed as "my-server" exposing a tool called list_items becomes my-server-list_items.

This naming convention is not documented anywhere — not in the SDK README, the type docstrings, or the SessionConfig / MCPRemoteServerConfig type definitions.

Impact

If a user sets available_tools or custom_agents[].tools using the bare MCP tool names (e.g., "list_items" instead of "my-server-list_items"), all MCP tools are silently filtered out. The model receives zero tools, returns a generic "I can't do that" response, and no error or warning is raised.

This is especially hard to debug because:

• No error is thrown when non-matching tool names are provided
• The on_pre_tool_use / on_post_tool_use hooks never fire (tools are filtered before invocation)
• The naming convention is an implementation detail of the CLI backend, not visible in the Python SDK source

Suggested fix

1. Document the <server-key>-<tool-name> convention in the README, in the SessionConfig docstring, and in the MCPRemoteServerConfig type definition.

2. Consider emitting a warning when available_tools contains names that don't match any registered tool, so users get feedback instead of silent failure.

Reproduction

from copilot import CopilotClient
from copilot.types import MCPRemoteServerConfig, SessionConfig

config: SessionConfig = {
    "model": "gpt-4.1",
    # BUG: these bare names don't match the prefixed names the backend uses
    "available_tools": ["list_tables", "run_query"],
    "mcp_servers": {
        "my-server": MCPRemoteServerConfig(
            type="http",
            url="https://example.com/mcp",
            tools=["*"],
        )
    },
}
# Result: model has zero tools, silently fails
# Fix: use "my-server-list_tables", "my-server-run_query"