Guide de débogage du serveur MCP

Ce guide décrit les techniques de débogage spécifiques aux serveurs MCP (Model Context Protocol) lors de l’utilisation du KIT DE développement logiciel (SDK) Copilot.

Dans cet article

Table des matières

Diagnostics rapides

Liste de vérification

Avant de plonger en profondeur, vérifiez ces principes de base :

  • Le fichier exécutable du serveur MCP existe et peut être exécuté
  • Chemin de commande correct (utilisez des chemins absolus en cas de doute)
  • Les outils sont activés (tools: ["*"] ou noms d’outils spécifiques)
  • Le serveur implémente correctement le protocole MCP (répond à initialize)
  • Aucun pare-feu/antivirus bloquant le processus (Windows)

Activer la journalisation du débogage MCP

Ajoutez des variables d’environnement à votre configuration de serveur MCP :

mcpServers: {
  "my-server": {
    type: "local",
    command: "/path/to/server",
    args: [],
    env: {
      MCP_DEBUG: "1",
      DEBUG: "*",
      NODE_DEBUG: "mcp",  // For Node.js MCP servers
    },
  },
}

Test des serveurs MCP indépendamment

Testez toujours votre serveur MCP en dehors du Kit de développement logiciel (SDK) en premier.

Test manuel du protocole

Envoyez une initialize demande via stdin :

# Unix/macOS
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

# Windows (PowerShell)
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | C:\path\to\your\mcp-server.exe

Réponse attendue :

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

Liste des outils de test

Après l’initialisation, demandez la liste des outils :

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

Réponse attendue :

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}}

Script de test interactif

Créez un script de test pour déboguer de manière interactive votre serveur MCP :

#!/bin/bash
# test-mcp.sh

SERVER="$1"

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Send initialized notification
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Keep stdin open
cat

Utilisation :

./test-mcp.sh | /path/to/mcp-server

Problèmes courants

Le serveur ne démarre pas

Symptômes: Aucun outil n’apparaît, aucune erreur n'est consignée.

Causes & Solutions :

CauseSolution
Chemin d’accès de commande incorrectUtilisez le chemin absolu : /usr/local/bin/server
Autorisation exécutable manquanteExécutez chmod +x /path/to/server
Dépendances manquantesVérifier avec ldd (Linux) ou exécuter manuellement
Problèmes de répertoire de travailDéfinir cwd dans la configuration

Déboguer en exécutant manuellement :

# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

Le serveur démarre, mais les outils n’apparaissent pas

Symptômes: Le processus serveur s’exécute, mais aucun outil n’est disponible.

Causes & Solutions :

  1. Outils non activés dans la configuration :

    mcpServers: {
  "server": {
    // ...
    tools: ["*"],  // Must be "*" or list of tool names
  },
}

  2. Le serveur n’expose pas les outils :

    • Tester la requête manuellement avec tools/list
    • Check Server implémente la tools/list méthode

  3. Échec de la négociation d’initialisation :

    • Le serveur doit répondre à initialize correctement
    • Le serveur doit gérer notifications/initialized

Outils répertoriés mais jamais appelés

Symptômes: Les outils apparaissent dans les journaux de débogage, mais le modèle ne les utilise pas.

Causes & Solutions :

  1. L’invite n’a pas besoin clairement de l’outil :

    // Too vague
await session.sendAndWait({ prompt: "What's the weather?" });

// Better - explicitly mentions capability
await session.sendAndWait({ 
  prompt: "Use the weather tool to get the current temperature in Seattle" 
});

  2. La description de l’outil n’est pas claire :

    // Bad - model doesn't know when to use it
{ name: "do_thing", description: "Does a thing" }

// Good - clear purpose
{ name: "get_weather", description: "Get current weather conditions for a city. Returns temperature, humidity, and conditions." }

  3. Problèmes de schéma d’outil :

    • Vérifier qu’il s’agit inputSchema d’un schéma JSON valide
    • Les champs obligatoires doivent être dans le required tableau

Erreurs de délai d’expiration

Symptômes:MCP tool call timed out Erreurs.

Solutions :

  1. Augmentez le délai d’expiration :

    mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

  2. Optimiser les performances du serveur :

    • Ajouter une journalisation de l’avancement pour identifier un goulot d’étranglement
    • Envisager des opérations asynchrones
    • Vérifier les E/S bloquantes

  3. Pour les outils de longue durée, envisagez de diffuser des réponses en continu si elles sont prises en charge.

erreurs de JSON-RPC

Symptômes: Erreurs d’analyse, erreurs de requête non valides.

Causes courantes :

  1. Les écritures du serveur dans stdout sont incorrectes :

    • Sortie de débogage redirigée vers stdout au lieu de stderr
    • Nouvelles lignes ou espaces blancs supplémentaires
    // Wrong - pollutes stdout
console.log("Debug info");

// Correct - use stderr for debug
console.error("Debug info");

  2. Problèmes d’encodage :

    • Vérifier l’encodage UTF-8
    • Sans BOM (indicateur d’ordre des octets)

  3. Trame de message :

    • Chaque message doit être un objet JSON complet
    • Délimité par nouvelle ligne (un message par ligne)

Problèmes spécifiques à la plateforme

Windows

Applications console / outils .NET

using GitHub.Copilot;

public static class McpDotnetConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["my-dotnet-server"] = new McpStdioServerConfig
            {
                Command = @"C:\Tools\MyServer\MyServer.exe",
                Args = new List<string>(),
                WorkingDirectory = @"C:\Tools\MyServer",
                Tools = new List<string> { "*" },
            },
            ["my-dotnet-tool"] = new McpStdioServerConfig
            {
                Command = "dotnet",
                Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
                WorkingDirectory = @"C:\Tools\MyTool",
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Correct configuration for .NET exe
["my-dotnet-server"] = new McpStdioServerConfig
{
    Command = @"C:\Tools\MyServer\MyServer.exe",  // Full path with .exe
    Args = new List<string>(),
    WorkingDirectory = @"C:\Tools\MyServer",  // Set working directory
    Tools = new List<string> { "*" },
}

// For dotnet tool (DLL)
["my-dotnet-tool"] = new McpStdioServerConfig
{
    Command = "dotnet",
    Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
    WorkingDirectory = @"C:\Tools\MyTool",
    Tools = new List<string> { "*" },
}

commandes npx

using GitHub.Copilot;

public static class McpNpxConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["filesystem"] = new McpStdioServerConfig
            {
                Command = "cmd",
                Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Windows needs cmd /c for npx
["filesystem"] = new McpStdioServerConfig
{
    Command = "cmd",
    Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
    Tools = new List<string> { "*" },
}

Problèmes de chemin d’accès

  • Utiliser des chaînes brutes (@"C:\path") ou des barres obliques ("C:/path")
  • Éviter les espaces dans les chemins lorsque cela est possible
  • Si des espaces sont requis, assurez-vous d’utiliser correctement les guillemets

Antivirus/pare-feu

Windows Defender ou d’autres AV peuvent bloquer :

  • Nouveaux exécutables
  • Processus de communication via stdin/stdout

Solution: Ajoutez des exclusions pour votre exécutable de serveur MCP.

macOS

Blocage par Gatekeeper

# If the server is blocked
xattr -d com.apple.quarantine /path/to/mcp-server

Chemins d’accès Homebrew

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

const mcpServers: Record<string, MCPStdioServerConfig> = {
  "my-server": {
    command: "/opt/homebrew/bin/node",
    args: ["/path/to/server.js"],
    tools: ["*"],
  },
};

// GUI apps may not have /opt/homebrew in PATH
mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

Problèmes d’autorisation

chmod +x /path/to/mcp-server

Bibliothèques partagées manquantes

# Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

Débogage avancé

Capturer tout le trafic MCP

Créez un script wrapper pour journaliser toutes les communications :

#!/bin/bash
# mcp-debug-wrapper.sh

LOG="/tmp/mcp-debug-$(date +%s).log"
ACTUAL_SERVER="$1"
shift

echo "=== MCP Debug Session ===" >> "$LOG"
echo "Server: $ACTUAL_SERVER" >> "$LOG"
echo "Args: $@" >> "$LOG"
echo "=========================" >> "$LOG"

# Tee stdin/stdout to log file
tee -a "$LOG" | "$ACTUAL_SERVER" "$@" 2>> "$LOG" | tee -a "$LOG"

Utilisez-le :

mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

Inspecter avec l’inspecteur MCP

Utilisez l’outil d’inspecteur MCP officiel :

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Cela fournit une interface utilisateur web pour :

  • Envoyer des demandes de test
  • Afficher les réponses
  • Inspecter les schémas d’outil

Incompatibilités de version du protocole

Vérifiez que votre serveur prend en charge la version du protocole utilisée par le Kit de développement logiciel (SDK) :

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

Si les versions ne correspondent pas, mettez à jour votre bibliothèque de serveurs MCP.

Liste de vérification du débogage

Lors de l’ouverture d’un problème ou de la demande d’aide, collectez :

  • Langue et version du Kit de développement logiciel (SDK)
  • Version de l’interface CLI (copilot --version)
  • Type de serveur MCP (Node.js, Python, .NET, Go, Rust, etc.)
  • Configuration complète du serveur MCP (secrets rédigés)
  • Résultat du test manuel initialize
  • Résultat du test manuel tools/list
  • Journaux de débogage du Kit de développement logiciel (SDK)
  • Messages d’erreur

Voir aussi