Créer un serveur MCP depuis zéro : tutoriel 2026 pour l'appel d'outils IA

Un grand modèle, aussi brillant soit-il, ne peut interroger une base de données, appeler une API ni lire vos notes locales sans « mains et pieds ». Le Model Context Protocol (MCP) standardise via JSON-RPC la connexion entre clients IA et capacités externes — en 2026, l'écosystème dépasse 13 000 serveurs ; OpenAI, Google et Microsoft le supportent pleinement. Problème : le Function Calling est propriétaire et fragmenté. Conclusion : à la fin de cet article, vous saurez développer, déboguer et déployer un MCP Server prêt pour la production. Plan : protocole → environnement → Hello World → Tools/Resources/Prompts → HTTP distant → debug → Docker → base de connaissances → écosystème.

1. Qu'est-ce que MCP ? Comprendre le protocole avant de coder

1.1 Genèse

Trois générations d'appel d'outils : Function Calling (format propriétaire OpenAI) → Plugins (écosystème ChatGPT, en déclin) → MCP (standard ouvert). Anthropic a open-sourcé MCP en novembre 2024 pour résoudre l'explosion N×M : chaque nouveau client IA imposait de réécrire l'intégration. MCP standardise la communication entre IA et outils externes — écrivez une fois, Cursor, Claude Desktop et VS Code en profitent. En 2026, la gouvernance relève de l'AAIF sous la Linux Foundation.

1.2 Architecture du protocole

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (votre développement)│
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (appel outil)  (lecture données) (modèles prompt)

Client : hôte du modèle (Claude Desktop, Cursor, agent personnalisé). Server : votre fournisseur de capacités. Trois piliers : Tools — fonctions appelables (recherche, calcul, SQL) ; Resources — données lisibles (fichiers, config, URLs) ; Prompts — modèles de prompt avec injection de paramètres.

1.3 Mécanisme de communication

Fondation : JSON-RPC 2.0. Transports : stdio (sous-processus local, zéro config réseau) et Streamable HTTP (spécification 2025-06-18 remplaçant HTTP+SSE, adapté au remote/multi-client). Cycle : handshake → négociation (tools/list) → requête/réponse → fermeture. ⚠️ En mode stdio local, interdiction d'imprimer des logs non-protocole sur stdout.

1.4 MCP vs alternatives

Dimension	MCP	OpenAI Function Calling	LangChain Tools
Standardisation	Protocole ouvert	Propriétaire	Lié au framework
Transport	stdio / Streamable HTTP	HTTP	HTTP
Multi-modèle	Oui	Non	Partiel
Resources/Prompts	Natif	Non	Non
Écosystème	13 000+ serveurs (2026)	Mature	Mature

2. Préparer l'environnement de développement

2.1 Choix du langage

Python (recommandé débutants) : SDK officiel mcp + décorateurs FastMCP, syntaxe épurée. TypeScript (frontend/fullstack) : @modelcontextprotocol/sdk + validation Zod, plus de 150 M de téléchargements npm. Cet article privilégie Python, TypeScript en référence.

2.2 Configuration

# Python
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

# TypeScript (référence)
npm init -y
npm install @modelcontextprotocol/sdk zod

2.3 Structure du projet

my-mcp-server/
├── server.py            # Point d'entrée
├── tools/               # Modules outils
│   ├── calculator.py
│   └── web_search.py
├── resources/           # Modules ressources
│   └── file_reader.py
├── prompts/             # Modèles de prompt
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

2.4 Outils de débogage

1) MCP Inspector : npx @modelcontextprotocol/inspector python server.py, UI sur localhost:6274. 2) Claude Desktop : ~/Library/Application Support/Claude/claude_desktop_config.json. 3) Cursor : Settings → MCP → mcpServers. Voir notre analyse approfondie du protocole MCP.

3. Premier MCP Server : Hello World

3.1 Serveur minimal

from mcp.server.fastmcp import FastMCP

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

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

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

3.2 Exécution et vérification

python server.py
# ou MCP Inspector
npx @modelcontextprotocol/inspector python server.py

3.3 Intégration Cursor / Claude Desktop

// claude_desktop_config.json ou Cursor MCP
{
  "mcpServers": {
    "my-first-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ Utilisez des chemins absolus pour Python et le script. Après redémarrage, say_hello doit apparaître dans le contexte outils.

4. Tools : développer des outils appelables par l'IA

4.1 Structure de base

La signature fonctionnelle sert de documentation : types et docstring sont convertis en JSON Schema par le SDK. Nommage : snake_case, sémantique (web_search plutôt que ws). Erreurs : retourner des chaînes structurées plutôt que des exceptions non capturées.

4.2 Types de paramètres

from pydantic import BaseModel, Field

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

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """Effectue une recherche web"""
    return [{"title": "Exemple", "url": "https://example.com"}]

4.3 Cas pratiques : 5 outils utiles

Outil	Usage	Implémentation
Calculateur	Expressions mathématiques	`eval` avec sandbox ou `ast`
Fichiers	Lecture/écriture locale	Répertoires autorisés, anti path traversal
HTTP	APIs externes	`httpx` + timeout 30s
Base de données	SQL lecture seule	Requêtes paramétrées, pas de DDL
Temps	Heure/fuseaux	`zoneinfo` stdlib

4.4 Outils asynchrones

import httpx

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

4.5 Bonnes pratiques de gestion d'erreurs

1) Erreurs structurées : {"error": "...", "code": "TIMEOUT"}. 2) Timeout : toute I/O limitée à 30s. 3) Autorisation : listes blanches au niveau Tool, sans compter sur la discipline du LLM.

5. Resources : permettre à l'IA de lire du contenu dynamique

5.1 Resource vs Tool

Resource = fournisseur de données (principalement lecture), Tool = exécuteur d'actions. Adressage URI : file://, http://, custom://.

5.2 Ressources statiques vs dynamiques

import json

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

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Profil utilisateur par ID"""
    return json.dumps({"user_id": user_id, "name": "Demo"})

5.3 Types de ressources

Texte (text/plain, application/json), binaire (images/PDF en base64), streaming (données temps réel via Streamable HTTP).

5.4 Cas pratique : serveur de ressources fichiers

Lister répertoires, lire fichiers, optionnellement s'abonner aux changements (resources/subscribe). En production, limiter strictement la racine — voir le design allowlist de mcp-server-filesystem.

6. Prompts : modèles de prompt réutilisables

6.1 Qu'est-ce qu'un MCP Prompt ?

Fragments de prompt prédéfinis avec paramètres dynamiques — cohérence d'équipe et maintenabilité. Complète les Agent Skills Cursor : MCP Prompt = couche protocole, Skill = manuel opérationnel.

6.2 Créer un modèle

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """Modèle de revue de code"""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"""Veuillez examiner ce code {language} :
1. Qualité et lisibilité
2. Bugs et failles de sécurité
3. Optimisations performance

```{language}
{code}
```"""
            )
        )
    ]

6.3 Prompts multi-tours

Modèles incluant user et assistant — simulation d'entretien, assistant debug avec questions de clarification.

7. Avancé : mode transport HTTP (MCP Server distant)

7.1 stdio vs Streamable HTTP

Caractéristique	stdio	Streamable HTTP
Déploiement	Processus local	Serveur distant
Latence	Très faible (<5 ms)	50–200 ms (réseau)
Multi-client	Non	Oui
Cas d'usage	Outils locaux, IDE	SaaS/équipe/7×24

⚠️ HTTP+SSE est déprécié depuis la spec 2025-06-18 — privilégiez Streamable HTTP.

7.2 Implémenter le transport HTTP

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

Production : uvicorn/gunicorn + reverse proxy. Serverless (Cloud Run/Lambda) : stateless_http=True car les sessions mémoire disparaissent au cold start.

7.3 Authentification et sécurité

Bearer Token, middleware API Key, liste blanche CORS, rate limiting (100 req/min/IP). Développement : lier 127.0.0.1, interdit d'exposer 0.0.0.0 sans auth. 2026 : plus de 30 CVE MCP, dont RCE CVSS 9.6 dans mcp-remote.

8. Débogage et tests

8.1 MCP Inspector

UI : lister Tools → appeler manuellement → voir JSON-RPC brut → simuler timeout/erreurs. Efficacité vs debug direct LLM : environ 10×.

8.2 Tests unitaires

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

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

8.3 Dépannage courant

Erreur	Cause	Solution
Outil absent dans l'IA	Chemin config incorrect	Vérifier chemins absolus config.json
Échec sérialisation JSON	Type retour non supporté	Convertir en str ou dict
Timeout déconnexion	Outil trop lent	Async + timeout 30s
Accès refusé	Chemin restreint	Configurer allowlist

9. Déploiement en production

9.1 Conteneurisation Docker

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

9.2 Déploiement cloud

Railway / Render : déploiement en un clic, environ 5–20 $/mois. AWS Lambda / Google Cloud Run : serverless. VPS dédié : Nginx + Let's Encrypt + systemd/launchd.

9.3 Monitoring et observabilité

Logs structurés (JSON Lines), métriques Prometheus (mcp_tool_calls_total), alertes Sentry, endpoint /health. Seuil d'alerte latence P99 : 5s.

9.4 Gestion des versions

Déclarer la version MCP au handshake ; évolutions rétrocompatibles ; négociation capabilities.

10. Projet pratique : MCP Server base de connaissances personnelle

10.1 Besoins

Permettre à l'IA de rechercher des notes Markdown locales, recherche sémantique, créer/mettre à jour des notes. Dans Cursor : « Qu'ai-je noté sur MCP la semaine dernière ? »

10.2 Choix techniques

Composant	Choix	Raison
Base vectorielle	ChromaDB / Qdrant	Léger, local, zero-ops
Modèle d'embedding	text-embedding-3-small	1536 dim., coût faible
Surveillance fichiers	watchfiles	Réindexation auto

10.3 Implémentation

Quatre modules : index_notes, semantic_search, write_note, ressource notes://{path}. Indexation ~1000 notes : 2–5 min (M4 Pro).

10.4 Démonstration

L'utilisateur saisit dans Cursor : « Que disaient mes notes sur le déploiement MCP la semaine dernière ? » → l'agent appelle semantic_search(query="déploiement MCP", days=7) → 3 extraits pertinents (similarité 0,82–0,91) → le LLM synthétise avec citations. Toute la bibliothèque reste hors du context window.

11. Écosystème MCP et perspectives

11.1 Serveurs MCP recommandés

mcp-server-filesystem, mcp-server-github, mcp-server-brave-search, mcp-server-postgres, mcp-server-slack. Registre officiel : 13 000+ serveurs.

11.2 Tendances 2026

Support des quatre géants ; MCP Marketplace ; OAuth 2.1 entreprise sur la roadmap ; complémentarité avec Google A2A (MCP = couche outils verticale, A2A = orchestration horizontale d'agents).

11.3 Prochaines étapes

① Lire la spec sur modelcontextprotocol.io ; ② publier votre premier MCP Server public ; ③ explorer MCP + Agent ; ④ contribuer à l'open source (SDK Python/TS).

12. Checklist en cinq étapes

Étape 1 — Hello World FastMCP, validation Inspector. Étape 2 — 3 Tools métier + 1 Resource. Étape 3 — Cursor / Claude Desktop (chemins absolus). Étape 4 — Streamable HTTP distant. Étape 5 — Docker + monitoring + audit sécurité.

13. Chiffres de référence

Indicateur	Valeur
Écosystème MCP Server (2026)	13 000+
Croissance 18 mois	7,8× (1 200 → 9 400+)
Téléchargements SDK TS	150 M+
CVE MCP 2026	30+
Timeout I/O Tool recommandé	30s
Index base connaissances (1000 notes)	2–5 min (M4 Pro)

14. Cas approfondi : du stdio local au nœud Mac distant

Un ingénieur IA exécutait Cursor + 5 MCP Server stdio (filesystem, postgres, brave-search, base de connaissances, navigateur) sur un MacBook Air. Mémoire unifiée 24 Go : 19 Go en usage permanent — surchauffe, throttling, couvercle fermé = déconnexion. Migration : Cursor en local ; 5 serveurs en Streamable HTTP sur Mac mini (64 Go), keepalive launchd ; connexion via url: http://node.macgpu.local:8000/mcp. P99 appels outils : local 180 ms → distant 95 ms (sans throttling) — plus stable.

Un VPS Windows/Linux peut héberger des MCP Server, mais pour les scénarios graphisme/multimédia + chaîne outils IA parallèles à Xcode, ComfyUI ou Final Cut, macOS reste souvent plus fluide. Le stdio local convient au développement ; la production 7×24 se prête mieux à un nœud Apple Silicon distant : mémoire unifiée pour appels Tool concurrents, portable réservé à l'orchestration.

Pour un environnement stable et louable hébergeant clusters MCP Server et Agent Gateway, envisagez le nœud Mac distant MACGPU : disponibilité 7×24, reverse proxy HTTP préconfiguré, mémoire unifiée non saturée par les sous-processus — du « ça tourne » au « ça tourne en confiance ».