Créer un MCP Server from scratch
Guide complet pour développeurs

Pourquoi l'IA a besoin d'un MCP Server : un LLM sans outils n'est qu'un cerveau qui parle

Les grands modèles ont une date limite d'entraînement et ne peuvent accéder à votre CRM, vos dépôts Git ou vos API internes. Avant 2024, vous écriviez du Function Calling pour Claude, des Plugins pour GPT et un autre format pour Cursor — changer de modèle = tout recommencer. Un MCP Server encapsule les capacités d'outils dans un processus indépendant : écrivez une fois, utilisez dans Claude Desktop, Cursor et Gemini.

Scénarios typiques : interroger Postgres depuis Claude Desktop ; faire lire la documentation projet et modifier le code par un Agent Cursor ; appeler votre système de tickets via HTTP MCP depuis GPT — le même Server sous-jacent.

Ce que ce guide livre : pas seulement du concept, mais un chemin de say_hello vers un Server de base de connaissances production avec recherche vectorielle. Public visé : développeurs avec bases Python ou TypeScript qui veulent étendre l'IA dans leur IDE ou application Desktop.

Six points de friction : pourquoi « envelopper une API » ne suffit pas

1. 01

   Verrouillage fournisseur : OpenAI Function Calling et Claude Tool Use utilisent des formats différents — chaque changement de fournisseur impose de réécrire la couche d'adaptation.

2. 02

   Outils non découvrables : les API REST reposent sur une documentation statique ; l'IA ne peut pas appeler tools/list à l'exécution pour découvrir les capacités seule.

3. 03

   Silos IDE : Cursor, extensions VS Code et plugins JetBrains définissent les outils séparément — vous maintenez N×M intégrations.

4. 04

   Contexte et données fragmentés : les LLM ne lisent pas fiabilément config, préférences utilisateur ou logs en direct — il faut des Resources en lecture seule standardisées.

5. 05

   Templates de prompt dispersés : code review, rapports d'incident, etc. n'ont pas de registre unifié ; chaque équipe copie-colle.

6. 06

   Chaos local vs distant : les sous-processus stdio conviennent au développement, mais les passerelles HTTP production, l'authentification et le monitoring manquent de patron commun (voir notre guide gouvernance sous-processus stdio).

Environnement de développement : Python FastMCP vs SDK TypeScript

Deux voies principales : Python mcp + FastMCP (data/scripts) et TypeScript @modelcontextprotocol/sdk (intégration Web/API, typage strict). Dépôts SDK : python-sdk, typescript-sdk.

# Voie Python
python -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic

# Voie TypeScript
npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

Structure de projet recommandée

my-mcp-server/
├── pyproject.toml          # ou package.json
├── src/
│   ├── server.py           # point d'entrée FastMCP
│   ├── tools/              # modules d'outils
│   ├── resources/          # fournisseurs Resource
│   └── prompts/            # templates Prompt
├── tests/
│   └── test_tools.py       # pytest + ClientSession
├── Dockerfile
└── README.md

Checklist en six étapes : environnement prêt

1. 01

   Choisir la stack : équipes data/ML → Python ; full-stack Node → TypeScript.

2. 02

   Créer un environnement virtuel et verrouiller les dépendances : pip freeze ou package-lock.json pour éviter la dérive de schéma.

3. 03

   Installer MCP Inspector : npx @modelcontextprotocol/inspector pour déboguer JSON-RPC visuellement.

4. 04

   Configurer Claude Desktop : éditer ~/Library/Application Support/Claude/claude_desktop_config.json et ajouter command/args du Server.

5. 05

   Configurer Cursor : Settings → MCP → Add Server ; pour stdio, python -m src.server ou chemin absolu.

6. 06

   Vérifier la connectivité Inspector : lancer le Server → connecter Inspector → confirmer que tools/list retourne une liste non vide.

// Exemple de config MCP Cursor / Claude Desktop
{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

Tools en pratique : du schéma à cinq outils production

Les Tools sont la capacité centrale du MCP : l'IA exécute des opérations avec effets de bord via tools/call. Chaque Tool expose un nom, une description et un inputSchema ; FastMCP utilise Pydantic pour la validation.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="Mot-clé de recherche")
    limit: int = Field(10, ge=1, le=100, description="Nombre de résultats")

@mcp.tool()
async def search_docs(params: SearchInput) -> str:
    """Rechercher dans la bibliothèque de documents"""
    results = await index.search(params.query, params.limit)
    return json.dumps(results, ensure_ascii=False)

Cinq patterns d'outils courants

• calculator : eval sécurisé ou ast.literal_eval ; jamais exec.
• file_read / file_write : liste blanche de répertoire racine pour éviter le path traversal.
• fetch_url (async) : httpx avec timeout et liste blanche de domaines.
• db_query : SQL lecture seule avec requêtes paramétrées ; pas de DDL.
• get_current_time : retourne l'heure ISO8601 avec fuseau pour corriger les hallucinations temporelles du LLM.

import httpx
from datetime import datetime, timezone

@mcp.tool()
async def fetch_url(url: str) -> str:
    """HTTP GET du contenu URL (domaines en liste blanche)"""
    allowed = ("api.github.com", "nodemini.com")
    if not any(url.startswith(f"https://{d}") for d in allowed):
        raise ValueError(f"Domain not allowed: {url}")
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:8000]

@mcp.tool()
def get_current_time() -> str:
    """Retourner l'heure UTC actuelle"""
    return datetime.now(timezone.utc).isoformat()

Bonnes pratiques de gestion d'erreurs

• Erreurs structurées : raise ValueError("message lisible") — le Client renvoie le message au LLM.
• Distinction réessayable vs fatal : timeouts réseau marqués retryable ; refus de permission = échec immédiat.
• Logs et masquage : journaliser nom d'outil et latence ; ne jamais loguer clés API complètes ou PII.
• Idempotence : opérations d'écriture avec idempotency_key pour éviter les données corrompues par appels Agent en double.

Prompts : modèles de conversation multi-tours réutilisables

Un Prompt MCP est un squelette de conversation enregistré sur le Server. Le Client récupère une liste de messages via prompts/get, avec rôles user / assistant et placeholders de paramètres — l'équipe partage code review et workflows d'incident sans fichiers prompt individuels.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str = "python") -> list[PromptMessage]:
    """Template multi-tours Code Review standardisé"""
    return [
        PromptMessage(role="user", content=TextContent(
            type="text",
            text=f"Vous êtes un ingénieur {language} senior. Auditez le diff suivant selon sécurité, performance et lisibilité."
        )),
        PromptMessage(role="assistant", content=TextContent(
            type="text",
            text="Collez le diff ou indiquez le numéro de PR — je produirai un review structuré selon la CHECKLIST."
        )),
    ]

Les templates multi-tours peuvent imbriquer des variables ({ticket_id}, {severity}). Le Server gère les versions ; quand le Client met à jour le Server, toute l'équipe obtient les standards de review à jour.

Débogage et tests : Inspector + tests unitaires pytest

MCP Inspector est le débogueur visuel officiel : connectez via stdio ou URL, envoyez manuellement tools/list et tools/call, inspectez les allers-retours JSON-RPC — bien plus efficace que de deviner depuis les logs Cursor.

# tests/test_tools.py
import pytest
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

@pytest.mark.asyncio
async def test_say_hello():
    params = StdioServerParameters(command="python", args=["-m", "src.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("say_hello", {"name": "MCP"})
            assert "MCP" in result.content[0].text

Table de référence des erreurs courantes

Projet pratique : MCP Server base de connaissances ChromaDB

Vectorisez Wiki interne / docs Markdown et exposez les outils index_document, search_knowledge et write_note pour qu'un Agent Cursor puisse « consulter la base de connaissances avant d'écrire le code ».

Exigences : indexation incrémentale (watchfiles sur docs/), recherche sémantique Top-K, écriture scratchpad optionnelle.

import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

client = chromadb.PersistentClient(path="./data/chroma")
collection = client.get_or_create_collection(
    "wiki", embedding_function=SentenceTransformerEmbeddingFunction()
)

@mcp.tool()
def search_knowledge(query: str, top_k: int = 5) -> str:
    """Recherche sémantique dans la base de connaissances interne"""
    hits = collection.query(query_texts=[query], n_results=top_k)
    return json.dumps(hits["documents"][0], ensure_ascii=False)

@mcp.tool()
def index_document(path: str) -> str:
    """Indexer un fichier Markdown"""
    text = open(path).read()
    collection.upsert(ids=[path], documents=[text], metadatas=[{"path": path}])
    return f"Indexed: {path}"

Requête démo Cursor : « Recherche dans la base de connaissances les docs sur le déploiement MCP HTTP, puis résume une checklist de mise en ligne en trois étapes » — l'Agent appelle d'abord search_knowledge, puis répond depuis le contexte retrouvé. Remplacez le store vectoriel par Qdrant (gRPC distant) à plus grande échelle.