Création de serveurs MCP (Model Context Protocol) pour exposer des outils, ressources et prompts aux LLMs. Se déclenche avec "MCP", "Model Context Protocol", "MCP server", "MCP tool", "MCP resource", "serveur MCP", "connecter Claude à", "exposer une API à Claude", "claude desktop config". Also triggers on "build an MCP server", "expose tools to Claude", "Model Context Protocol server".
Création de serveurs MCP (Model Context Protocol) pour exposer des outils, ressources et prompts aux LLMs. Se déclenche avec "MCP", "Model Context Protocol", "MCP server", "MCP tool", "MCP resource", "serveur MCP", "connecter Claude à", "exposer une API à Claude", "claude desktop config". Also triggers on "build an MCP server", "expose tools to Claude", "Model Context Protocol server".
MCP Server Builder
Quand utiliser ce skill
Crée un serveur MCP quand l'objectif est d'exposer une capacité (API, base de données, système de fichiers, service métier) à un LLM de façon structurée. Les cas typiques :
Connecter Claude Desktop ou Cursor à un outil interne
Wrapper une API REST existante pour qu'elle soit appelable par un agent
Exposer des ressources en lecture (documents, données) au contexte de Claude
Créer des prompt templates réutilisables pour un workflow métier récurrent
Critères de décision : transport
Contexte
Transport recommandé
Claude Desktop / Cursor / usage local
stdio
Serveur réseau, multi-clients
Streamable HTTP (depuis SDK 1.x)
Compatibilité legacy SSE requise
SSE (déprécié en 2025)
Edge / Cloudflare Workers
Streamable HTTP avec fetch handler
Workflow
1. Initialisation du projet
Python (recommandé pour démarrages rapides) :
uv init my-mcp-server && cd my-mcp-server
uv add "mcp[cli]"
uv run mcp dev server.py # hot-reload avec MCP Inspector
TypeScript (recommandé pour production Node.js) :
npx @modelcontextprotocol/create-server my-mcp-server
cd my-mcp-server && npm install
npm run build
Structure minimale Python :
my-mcp-server/
server.py
pyproject.toml
.env # secrets, jamais committé
2. Squelette serveur minimal
Python — stdio (Claude Desktop) :
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-server")
@mcp.tool()asyncdefping() -> str:
"""Vérifie que le serveur répond."""return"pong"if __name__ == "__main__":
mcp.run() # transport stdio par défaut
TypeScript — stdio :
import { McpServer } from"@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from"@modelcontextprotocol/sdk/server/stdio.js";
import { z } from"zod";
const server = newMcpServer({ name: "my-server", version: "1.0.0" });
server.tool("ping", "Vérifie que le serveur répond", {}, async () => ({
content: [{ type: "text", text: "pong" }],
}));
const transport = newStdioServerTransport();
await server.connect(transport);
3. Définir des Tools
Règles de nommage : snake_case, verbe d'action, sans ambiguïté (search_emails > emails).
La description est lue par le LLM pour décider quand appeler l'outil — elle doit être précise et inclure les cas limites.
from pydantic import BaseModel, Field
classSearchInput(BaseModel):
query: str = Field(description="Texte à rechercher, supporte la syntaxe Lucene")
limit: int = Field(default=10, ge=1, le=100, description="Nombre de résultats max")
since: str | None = Field(default=None, description="Filtre date ISO 8601, ex: 2026-01-01")
@mcp.tool()asyncdefsearch_documents(params: SearchInput) -> list[dict]:
"""
Recherche dans la base documentaire interne.
Retourne titre, extrait, url et score de pertinence.
Utiliser quand l'utilisateur cherche un document, une procédure ou une politique.
"""
results = await db.search(params.query, params.limit, params.since)
return [{"title": r.title, "snippet": r.snippet, "url": r.url, "score": r.score}
for r in results]
4. Définir des Resources
Les resources exposent des données en lecture sans action. Le LLM peut les inclure dans son contexte.
@mcp.resource("config://app/{env}")asyncdefget_config(env: str) -> str:
"""Configuration de l'application pour l'environnement donné."""if env notin ("dev", "staging", "prod"):
raise ValueError(f"Environnement inconnu : {env}")
data = load_config(env)
return json.dumps(data, indent=2)
URI schemes utiles : file://, db://, api://, config://, doc://.
5. Définir des Prompts
@mcp.prompt()defcode_review_prompt(language: str, code: str) -> list[dict]:
"""Template de revue de code réutilisable."""return [
{"role": "user", "content": f"Revois ce code {language} :\n\n```{language}\n{code}\n```\nFocus : sécurité, perf, lisibilité."}
]
Secrets dans les descriptions — Ne jamais inclure de clé API, token ou donnée sensible dans description d'un outil (le LLM peut les loguer ou les retourner dans ses réponses). Passer les secrets via env dans la config client.
Outils trop génériques — Un outil execute_sql(query: str) sans validation est dangereux. Préférer des outils spécialisés (list_users, get_order_by_id) avec validation Pydantic stricte.
Absence de timeout — Les handlers stdio bloquants font geler Claude Desktop. Toujours utiliser asyncio.wait_for avec timeout.
import asyncio
@mcp.tool()asyncdefslow_api_call(params: MyInput) -> dict:
try:
returnawait asyncio.wait_for(external_api(params), timeout=15.0)
except asyncio.TimeoutError:
raise McpError(ErrorCode.INTERNAL_ERROR, "Timeout API après 15s")
Retours non-sérialisables — Tout retour doit être JSON-sérialisable. Convertir les objets métier (datetime, Decimal, custom classes) avant de retourner.
Mélanger transport stdio et logs sur stdout — En stdio, stdout est le canal MCP. Les logs doivent aller sur stderr ou dans un fichier.
URI de ressource non-canoniques — Les templates d'URI (users/{id}) doivent correspondre exactement au pattern déclaré. Un mismatch rend la ressource silencieusement inaccessible.
Bonnes pratiques 2026
Utiliser FastMCP (Python) ou McpServer (TS SDK 1.x+) plutôt que les bas-niveaux Server/Protocol — l'API haut-niveau gère le cycle de vie, la validation et le routing.
Streamable HTTP est le standard réseau depuis 2025 — éviter SSE pour tout nouveau projet.
Versionner le serveur dans McpServer({ name, version }) — permet aux clients de détecter les mises à jour.
Déclarer uniquement les capabilities réellement implémentées dans capabilities: { tools: {}, resources: {} } — évite les erreurs de négociation.
Pour les agents Claude Code : préférer des outils idempotents avec des noms d'action clairs ; documenter les effets de bord dans la description.
Tester systématiquement avec MCP Inspector avant intégration client — il affiche les erreurs de schéma que le client LLM silencerait.
