Colisões de Métodos de Extensão do MCP Python SDK: Falhar Antes do Servidor Iniciar

Colisões de métodos de extensão do SDK Python MCP são defeitos de configuração, não casos extremos em tempo de execução. Se duas extensões reivindicarem o mesmo método — ou uma reivindicar um método central do MCP — o servidor deve rejeitar essa configuração antes de aceitar uma solicitação. Eu prefiro tornar a propriedade do método um contrato executável, para que a ordem de registro nunca decida qual manipulador vence.

A documentação oficial do SDK Python MCP sobre extensões define três salvaguardas úteis: métodos centrais não podem ser registrados como métodos de extensão, métodos de extensão duplicados são rejeitados durante o registro, e cada ligação deve declarar pelo menos uma versão de protocolo suportada.

Por que colisões devem falhar durante a inicialização

Uma extensão adiciona comportamento específico do fornecedor à mesma tabela de despacho usada pelo resto do servidor. Isso torna os nomes dos métodos parte do contrato público do servidor.

Considere duas extensões configuradas de forma independente que ambas expõem:

com.example/catalog.search

Um registro que prioriza a última escrita faria com que o manipulador ativo dependesse da ordem das extensões. Reordenar a configuração poderia alterar silenciosamente o comportamento da solicitação sem mudar a chamada do cliente.

O contrato mais seguro é um proprietário por nome de método. No exemplo, uma extensão válida inicia normalmente, enquanto uma segunda extensão que reivindica o mesmo método faz com que a construção do MCPServer levante um ValueError.

Métodos centrais do protocolo têm uma fronteira ainda mais forte. Uma extensão de fornecedor não deve substituir métodos como tools/list. O guardião de método central de extensão do SDK rejeita essa ligação quando MethodBinding é construído.

O exemplo visa a versão do protocolo 2026-07-28, anunciada no post final de lançamento do MCP do projeto, e fixa o pacote estável mcp==2.1.1 package para que as verificações sejam reproduzíveis.

Construir um MethodBinding com versão fixa

Começo com um método com namespace e uma versão de protocolo explícita definida:

PROTOCOL_VERSION = "2026-07-28"
EXTENSION_ID = "com.example/catalog"
METHOD = "com.example/catalog.search"


def search_binding(method: str = METHOD) -> MethodBinding:
    return MethodBinding(
        method,
        SearchParams,
        search,
        protocol_versions=frozenset({PROTOCOL_VERSION}),
    )

O prefixo de domínio reverso mantém o método do fornecedor separado dos nomes centrais do MCP. Mais importante, protocol_versions declara exatamente onde a ligação é acessível.

Essa validação da versão do protocolo previne um erro de configuração sutil. Um conjunto vazio descreve um método que não pode ser usado sob nenhuma versão de protocolo, então o SDK o rejeita imediatamente:

def build_unreachable_binding() -> MethodBinding:
    return MethodBinding(
        METHOD,
        SearchParams,
        search,
        protocol_versions=frozenset(),
    )

A extensão válida retorna uma ligação:

class CatalogSearch(Extension):
    identifier = EXTENSION_ID

    def methods(self) -> Sequence[MethodBinding]:
        return [search_binding()]

Uma segunda extensão deliberadamente retorna o mesmo nome de método:

class ShadowSearch(Extension):
    identifier = "com.example/catalog-shadow"

    def methods(self) -> Sequence[MethodBinding]:
        return [search_binding()]

Nenhuma das classes é inerentemente inválida isoladamente. A colisão aparece quando ambas são registradas em um servidor:

MCPServer(
    "extension-contract",
    extensions=[CatalogSearch(), ShadowSearch()],
)

Esta é a fronteira de método duplicado de MethodBinding que quero testar: o registro do servidor vê dois proprietários e se recusa a iniciar.

Verificar essa fronteira durante a construção mantém a falha próxima da configuração que a causou. Uma implantação nunca chega ao ponto em que a primeira solicitação infeliz descobre um manipulador ambíguo. Isso também torna o teste de regressão independente da ordem das extensões: trocar as duas classes não pode transformar a falha em sucesso. Em um servidor maior, eu manteria esses testes de propriedade ao lado da raiz de composição, onde pacotes opcionais são montados.

Verifique colisões de métodos de extensão do SDK Python MCP offline

O runnab