Usando servidores MCP com o SDK do GitHub Copilot

Observação

Esse é um recurso em evolução. Consulte issue #36 para acompanhar a discussão em andamento.

O que é MCP?

O PROTOCOLO MCP (Model Context Protocol) é um padrão aberto para conectar assistentes de IA a ferramentas externas e fontes de dados. Os servidores MCP podem:

Executar código ou scripts
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	Description	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

Configuration

Node.js/TypeScript

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: ["*"],
        },
    },
});

Python

import asyncio
from copilot import CopilotClient
from copilot.session import PermissionHandler

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5", mcp_servers={
        # Local MCP server (stdio)
        "my-local-server": {
            "type": "local",
            "command": "python",
            "args": ["./mcp_server.py"],
            "env": {"DEBUG": "true"},
            "cwd": "./servers",
            "tools": ["*"],
            "timeout": 30000,
        },
        # Remote MCP server (HTTP)
        "github": {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": {"Authorization": "Bearer ${TOKEN}"},
            "tools": ["*"],
        },
    })

    response = await session.send_and_wait("List my recent GitHub notifications")
    print(response.data.content)

    await client.stop()

asyncio.run(main())

Go

package main

import (
    "context"
    "log"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-5",
        MCPServers: map[string]copilot.MCPServerConfig{
            "my-local-server": copilot.MCPStdioServerConfig{
                Command: "node",
                Args:    []string{"./mcp-server.js"},
                Tools:   []string{"*"},
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer session.Disconnect()

    // Use the session...
}

.NET

using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5",
    McpServers = new Dictionary<string, McpServerConfig>
    {
        ["my-local-server"] = new McpStdioServerConfig
        {
            Command = "node",
            Args = new List<string> { "./mcp-server.js" },
            Tools = new List<string> { "*" },
        },
    },
});

Ferramenta de configuração

Você pode controlar quais ferramentas estão disponíveis para um servidor MCP usando o tools campo.

Permitir todas as ferramentas

Use "*" para habilitar todas as ferramentas fornecidas pelo servidor MCP:

tools: ["*"]

Permitir ferramentas específicas

Forneça uma lista de nomes de ferramentas para restringir o acesso:

tools: ["bash", "edit"]

Somente as ferramentas listadas estarão disponíveis para o agente.

Desabilitar todas as ferramentas

Use uma matriz vazia para desabilitar todas as ferramentas:

tools: []

Notes

O tools campo define quais ferramentas são permitidas.
Não há nenhuma configuração separada allowou disallow—o acesso à ferramenta é controlado diretamente por meio desta lista.

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();

Saída:

Session created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a
Response: The allowed directory is `/tmp`, which contains various files
and subdirectories including temporary system files, log files, and
directories for different applications.

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	Description
`type`
`"local"` ou `"stdio"`	No	Tipo de servidor (padrão é local)
`command`	`string`	Yes	Comando a ser executado
`args`	`string[]`	Yes	Argumentos de comando
`env`	`object`	No	Variáveis de ambiente
`cwd`	`string`	No	Diretório de trabalho
`tools`	`string[]`	No	Ferramentas para habilitar (`["*"]` para todos, `[]` para nenhum)
`timeout`	`number`	No	Tempo limite em milissegundos

Servidor remoto (HTTP/SSE)

Propriedade	Tipo	Obrigatório	Description
`type`
`"http"` ou `"sse"`	Yes	Tipo de servidor
`url`	`string`	Yes	URL do servidor
`headers`	`object`	No	Cabeçalhos HTTP (por exemplo, para autenticação)
`tools`	`string[]`	No	Ferramentas para habilitar
`timeout`	`number`	No	Tempo limite em milissegundos

Troubleshooting

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

Verificar se o servidor MCP é iniciado corretamente
- Verifique se o comando e os args estão corretos
- Verifique se o processo do servidor não falha na inicialização
- Procure por mensagens de erro no stderr
Verificar a configuração da ferramenta
- Certifique-se de que tools esteja definido como ["*"] ou liste as ferramentas específicas necessárias
- Uma matriz [] vazia significa que nenhuma ferramenta está habilitada
Verificar a conectividade para servidores remotos
- Verifique se a URL está acessível
- Verifique se os cabeçalhos de autenticação estão corretos

Problemas comuns

Issue	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

Para obter diretrizes detalhadas de depuração, consulte o Guia de depuração do servidor MCP.

Especificação do protocolo de contexto do modelo
Diretório de servidores MCP – servidores MCP da comunidade
servidor MCP GitHub – Servidor MCP GitHub oficial
Crie seu primeiro aplicativo com tecnologia do Copilot – Noções básicas do SDK e ferramentas personalizadas
Guia de depuração – Depuração em todo o SDK

Consulte também

Guia de depuração do servidor MCP – Solução de problemas detalhada do MCP
Problema nº 9 – Pergunta de uso original das ferramentas MCP
Problema nº 36 – Problema de acompanhamento da documentação do MCP

Usando servidores MCP com o SDK do GitHub Copilot

Neste artigo