Usando servidores MCP com o SDK do Copilot

Observação

          SDK do Copilot está atualmente em versão prévia técnica. A funcionalidade e a disponibilidade estão sujeitas a alterações.

O SDK do Copilot pode integrar-se com servidores MCP (Protocolo de Contexto de Modelo) para estender os recursos do assistente com ferramentas externas. Os servidores MCP são executados como processos separados e expõem ferramentas (funções) que Copilot podem invocar durante conversas.

O que é MCP?

          [O PROTOCOLO MCP (Model Context Protocol)](https://modelcontextprotocol.io/) é um padrão aberto para conectar assistentes de IA a ferramentas externas e fontes de dados. Os servidores MCP podem executar scripts ou códigos, consultar bancos de dados, acessar sistemas de arquivos, chamar APIs externas e muito mais.

Tipos de servidores

O SDK dá suporte a dois tipos de servidores MCP:

Tipo	Descrição	Caso de uso

          **Local/Stdio** | É executado como um subprocesso, comunica-se por meio de stdin/stdout | Ferramentas locais, acesso a arquivos, scripts personalizados |

| HTTP/SSE | Servidor remoto acessado via HTTP | Serviços compartilhados, ferramentas hospedadas na nuvem |

Configuração

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5",
    mcpServers: {
        // Local MCP server (stdio)
        "my-local-server": {
            type: "local",
            command: "node",
            args: ["./mcp-server.js"],
            env: { DEBUG: "true" },
            cwd: "./servers",
            tools: ["*"],  // "*" = all tools, [] = none, or list specific tools
            timeout: 30000,
        },
        // Remote MCP server (HTTP)
        "github": {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/",
            headers: { "Authorization": "Bearer ${TOKEN}" },
            tools: ["*"],
        },
    },
});

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Início rápido: servidor MCP do sistema de arquivos

Aqui está um exemplo de trabalho completo usando o servidor MCP oficial @modelcontextprotocol/server-filesystem :

import { CopilotClient } from "@github/copilot-sdk";

async function main() {
    const client = new CopilotClient();

    // Create session with filesystem MCP server
    const session = await client.createSession({
        mcpServers: {
            filesystem: {
                type: "local",
                command: "npx",
                args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
                tools: ["*"],
            },
        },
    });

    console.log("Session created:", session.sessionId);

    // The model can now use filesystem tools
    const result = await session.sendAndWait({
        prompt: "List the files in the allowed directory",
    });

    console.log("Response:", result?.data?.content);

    await session.disconnect();
    await client.stop();
}

main();

Dica

Você pode usar qualquer servidor MCP do Diretório de Servidores MCP. As opções populares incluem @modelcontextprotocol/server-github, @modelcontextprotocol/server-sqlitee @modelcontextprotocol/server-puppeteer.

Opções de configuração

Servidor Local/Stdio

Propriedade	Tipo	Obrigatório	Descrição
`type`

          `"local"` ou `"stdio"` | No | Tipo de servidor (padrão é local) |

Servidor remoto (HTTP/SSE)

Propriedade	Tipo	Obrigatório	Descrição
`type`

          `"http"` ou `"sse"` | Sim | Tipo de servidor |

Solução de problemas

Ferramentas que não aparecem ou não estão sendo invocadas

       **Verifique se o servidor MCP é iniciado corretamente**— Verifique se o comando e os argumentos estão corretos e verifique se o processo do servidor não falha na inicialização. Procure a saída de erro no stderr.

       **Verifique a configuração da ferramenta** — Certifique-se de que `["*"]` está definido para `tools` ou lista as ferramentas específicas de que você precisa. Uma matriz `[]` vazia significa que nenhuma ferramenta está habilitada.

       **Verificar a conectividade para servidores remotos** — verifique se a URL está acessível e verifique se os cabeçalhos de autenticação estão corretos.

Problemas comuns

Questão	Solução
"Servidor MCP não encontrado"	Verifique se o caminho do comando está correto e executável
"Conexão recusada" (HTTP)	Verifique a URL e verifique se o servidor está em execução
Erros de "tempo limite"	Aumente o valor do `timeout` ou verifique o desempenho do servidor
As ferramentas funcionam, mas não são chamadas	Verifique se o prompt exige claramente a funcionalidade da ferramenta

Leitura adicional

        [Especificação do Protocolo de Contexto do Modelo](https://modelcontextprotocol.io/)

        [Diretório de servidores MCP](https://github.com/modelcontextprotocol/servers) — servidores MCP da comunidade

        [Servidor MCP do GitHub](https://github.com/github/github-mcp-server) – servidor MCP oficial GitHub

Quem pode usar esse recurso?

Neste artigo