Créer un MCP Server de zéro : guide complet pour les développeurs

Les modèles actuels peinent à accéder aux outils externes et aux données en temps réel — c'est précisément le vide que MCP comble. Vous voulez que Claude interroge une base, que GPT appelle une API REST, que Cursor manipule le système de fichiers : MCP fournit un contrat commun. L'appel d'outils a suivi l'évolution Function Calling → Plugins → MCP : Function Calling reste lié à un éditeur ; les plugins restent fermés ; MCP, lui, est un standard ouvert multi-modèle et multi-client.

Conçu par Anthropic en novembre 2024, MCP vise à standardiser la communication entre l'IA et les outils externes, en sortant du piège N modèles × M outils = N×M intégrations sur mesure. À la fin de ce guide, vous serez capable de développer et déployer un MCP Server prêt pour la production.

• Duplication permanente : réécrire la logique d'accès au système de fichiers pour Cursor, Claude Desktop et VS Code.
• Changement de modèle = réécriture : migrer de Claude vers GPT implique de reconstruire toute la couche d'intégration.
• Pas de standard pour ressources et prompts : Function Calling ne gère que l'invocation de fonctions, sans exposer nativement des ressources en lecture seule ni des modèles de prompt réutilisables.
• Débogage opaque : en cas d'échec d'appel d'outil, aucun inspecteur unifié ni journal JSON-RPC partagé.

Le Client vit côté modèle (Claude Desktop, Cursor, client personnalisé) ; le Server est le fournisseur de capacités que vous développez. Ils communiquent en JSON-RPC 2.0, via stdio (processus local) ou HTTP + SSE (service distant). Le cycle de vie suit : poignée de main d'initialisation → négociation des capacités → requêtes/réponses → fermeture.

Le Server expose trois capacités fondamentales :

• Tools : fonctions invocables par l'IA (recherche, calcul, requête base de données)
• Resources : contenus lisibles par l'IA (fichiers, URL, flux de données)
• Prompts : modèles de prompt prédéfinis

Python (recommandé pour débuter) : SDK officiel mcp, syntaxe concise avec FastMCP. TypeScript (recommandé pour front-end et full-stack) : SDK officiel @modelcontextprotocol/sdk. Ce guide privilégie Python ; TypeScript est indiqué en parallèle lorsque pertinent.

# Python
python -m venv .venv
source .venv/bin/activate
pip install mcp

# TypeScript (miroir)
npm init -y
npm install @modelcontextprotocol/sdk

Structure de projet recommandée :

my-mcp-server/
├── server.py
├── tools/
│   ├── calculator.py
│   └── web_search.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

Outils de débogage : MCP Inspector (interface officielle), Claude Desktop pour les tests locaux, configuration .cursor/mcp.json dans Cursor. Documentation officielle sur modelcontextprotocol.io.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """Saluer une personne par son nom"""
    return f"Hello, {name}! Voici votre premier outil MCP."

if __name__ == "__main__":
    mcp.run()

python server.py
npx @modelcontextprotocol/inspector python server.py

Dans .cursor/mcp.json (Cursor) ou claude_desktop_config.json (Claude Desktop), configurez command et args pour pointer vers python server.py. Redémarrez le client et vérifiez que l'outil apparaît dans le contexte IA.

La signature de fonction sert de documentation : types de paramètres, type de retour et docstring sont convertis par MCP en JSON Schema pour le modèle. Utilisez snake_case pour les noms ; renvoyez des erreurs structurées plutôt que des exceptions brutes.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Mot-clé de recherche")
    max_results: int = Field(default=5, description="Nombre maximal de résultats")
    language: str = Field(default="fr", description="Langue des résultats")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """Effectuer une recherche web et retourner une liste de résultats"""
    ...

Cinq outils pratiques à implémenter pour s'entraîner :

• Calculatrice : évaluation d'expressions mathématiques (eval nécessite un bac à sable)
• Lecture/écriture de fichiers : accès aux fichiers locaux dans un répertoire autorisé
• Requêtes HTTP : appel d'API REST externes
• Requête base de données : exécution de SQL en lecture seule
• Outil horaire : heure courante, conversion de fuseau horaire

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Récupérer le contenu d'une URL"""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text

Bonnes pratiques : renvoyer des erreurs structurées, définir un timeout (recommandé 30 s), valider les permissions côté Server et ne jamais exposer les identifiants dans la configuration client.

Resource vs Tool : une Resource fournit des données (lecture seule) ; un Tool exécute une action. Adressage par URI : file://, http://, custom://.

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
  return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    user = db.query_user(user_id)
    return json.dumps(user)

Types de ressources : texte (text/plain, application/json), binaire (images, PDF) et flux (données temps réel). Un serveur de ressources système de fichiers peut lister des répertoires, lire des fichiers et écouter les changements (abonnement aux ressources).

Un Prompt MCP est un fragment de prompt prédéfini, avec injection dynamique de paramètres, pour garantir cohérence et maintenabilité. Vous pouvez définir des modèles multi-tours incluant user et assistant — idéal pour revue de code, simulation d'entretien ou assistant de débogage.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"Veuillez examiner le code {language} suivant..."
            )
        )
    ]

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

En production, configurez l'authentification Bearer Token, un middleware de validation de clé API, CORS et la limitation de débit. Centralisez les identifiants côté Server, pas dans chaque client.

Point de référence 1 : en 2026, l'écosystème MCP compte plus de 10 000 serveurs.

Point de référence 2 : après adoption de MCP, les entreprises constatent une baisse de 38 à 55 % du coût de développement d'intégrations d'outils (fourchette observée dans les études sectorielles).

Point de référence 3 : le SDK Python MCP dépasse 5 millions de téléchargements mensuels sur PyPI (T2 2026).

Utilisez MCP Inspector pour lancer l'interface de débogage, tester les appels Tools, consulter les journaux JSON-RPC et simuler des scénarios d'erreur. Les tests unitaires peuvent démarrer le Server en sous-processus et appeler via ClientSession :

from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async with stdio_client(StdioServerParameters(
    command="python", args=["server.py"]
)) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("calculate", {"expression": "2 + 2"})
        assert result.content[0].text == "4"

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

Options de déploiement : Railway / Render (déploiement rapide pour projets personnels), AWS Lambda / Google Cloud Run (serverless), VPS dédié (avec proxy inverse Nginx). Observabilité recommandée : journaux structurés, métriques Prometheus sur les appels d'outils, alertes Sentry, endpoint de health check. Déclarez la version du protocole MCP et adoptez une stratégie de mise à jour d'outils rétrocompatible.

Besoin : permettre à l'IA de rechercher des notes Markdown locales, d'effectuer une recherche sémantique (vectorielle) et de créer ou mettre à jour des notes.

Stack technique : base vectorielle locale ChromaDB / Qdrant ; modèle d'embedding text-embedding-3-small ; surveillance de fichiers watchfiles.

• Outil d'indexation : scanner un répertoire, découper en blocs et écrire dans la base vectorielle
• Outil de recherche sémantique : retourner les Top-K fragments pertinents pour une requête
• Outil d'écriture : créer ou compléter des fichiers Markdown
• Service de ressources fichiers : exposer le contenu intégral des notes via Resource URI

Démonstration : dans Cursor, demandez « Qu'ai-je noté la semaine dernière sur MCP ? » — l'IA invoque l'outil de recherche MCP et renvoie les extraits pertinents.

Serveurs communautaires de référence : mcp-server-filesystem (système de fichiers), mcp-server-github (dépôts GitHub), mcp-server-brave-search (recherche web), mcp-server-postgres (base de données), mcp-server-slack (messages Slack).

Tendances 2026 : OpenAI, Google et Microsoft ont annoncé le support MCP ; gouvernance transférée à l'AAIF de la Linux Foundation ; MCP Marketplace en croissance ; standards de sécurité entreprise (OAuth 2.1) en cours d'intégration à la feuille de route.

Prochaines étapes : approfondir la spécification MCP ; développer et publier un serveur public ; explorer la combinaison MCP + Agent ; contribuer à l'écosystème open source (Python SDK, TypeScript SDK, Inspector).

1. 01
   Choisir le mode de transport : stdio pour le développement local ; HTTP+SSE pour le partage d'équipe ou l'appel distant Claude Code — centralisez les clés API côté Server.
2. 02
   Provisionner un Mac cloud depuis la console : connectez-vous à la console NUKCLOUD, choisissez 16 Go+ de mémoire (32 Go recommandés pour plusieurs serveurs en parallèle) ; essai horaire sur la page tarifs.
3. 03
   Installer Python 3.12 + mcp : après connexion SSH, exécutez pip install mcp httpx pydantic ; validez avec MCP Inspector en test fumée local.
4. 04
   Déployer le Server HTTP et exposer le port : mcp.run(host="0.0.0.0", port=8000) ; configurez middleware Bearer Token et CORS.
5. 05
   Valider l'intégration client : dans .cursor/mcp.json, pointez vers l'URL cloud ; confirmez que tools/list et tools/call passent les tests fumée.
6. 06
   Résidence launchd et abonnement fixe : rédigez un plist LaunchAgents pour maintenir le service 7×24 ; après le pilote, verrouillez la spec sur la page commander. Voir le runbook production NUKCLOUD.

Faire tourner un MCP Server HTTP sur un portable local ou un VPS partagé expose à des interruptions de session à la mise en veille, des déconnexions SSE liées à la bande passante et des conflits entre développeurs sur le même processus. Pour une connexion longue stable — Background Agents Cursor ou serveur de base de connaissances 7×24 — les nœuds Mac cloud NUKCLOUD multi-régions offrent une isolation locataire et une élasticité de spec mieux alignées avec les workflows MCP.