Public : développeurs backend ou IA qui veulent brancher Claude, Cursor ou VS Code sur APIs internes, bases de données et fichiers — sans réécrire une couche d'intégration par modèle. Résultat : un MCP Server fonctionnel, du prototype STDIO local au déploiement HTTP+SSE, avec un cas pratique base de connaissances pour workflows créatifs et techniques. Plan : rappel protocole, six erreurs fréquentes, matrices de décision, code Hello World / Tools / Resources / Prompts, débogage, huit étapes de mise en production, écosystème. Pour la couche protocole, voir le deep dive MCP.
tools/list, JSON Schema et sessions persistantes.PATH diffère entre Terminal et launchd.Ce guide est le compagnon pratique du article protocole : ici, vous construisez ; là, vous comprenez pourquoi MCP s'impose comme standard.
Le Host (Cursor, Claude Desktop, VS Code) embarque un MCP Client. Le Client maintient une session 1:1 avec chaque MCP Server en JSON-RPC 2.0. Le serveur expose Tools, Resources et Prompts, puis se connecte à vos systèmes — CRM, stockage créatif, Xcode build farm, etc.
| Capability | Rôle | Méthodes RPC | Cas d'usage créatif / tech |
|---|---|---|---|
| Tools | Actions avec effets de bord | tools/list, tools/call | Exporter une timeline Final Cut, déclencher un build Xcode, créer un ticket Jira |
| Resources | Contexte lisible (URI) | resources/list, resources/read | Brand guidelines, LUTs, storyboards Markdown, specs design system |
| Prompts | Modèles réutilisables | prompts/list, prompts/get | Review colorimétrique, checklist livraison client, triage incident pipeline |
| Transport | Usage | Contrainte |
|---|---|---|
| STDIO | Dev local, poste unique | Démarrage < 5 ms (bundle épinglé) ; un processus par instance |
| HTTP + SSE | Équipe distante, partage | Session affinity ; TLS au reverse proxy |
Prérequis : Node.js 20 LTS ou Python 3.11+, Git, un Host compatible MCP. Sur Mac Apple Silicon, alignez la version Node/Python entre postes — l'écart d'environnement est la cause n°1 des outils « non enregistrés » dans les studios qui alternent MacBook et Mac mini.
mkdir mcp-hello && cd mcp-hello npm init -y npm install @modelcontextprotocol/sdk zod # Python : python3 -m venv .venv && pip install mcp
| SDK | Package | Atout sur écosystème Apple |
|---|---|---|
| TypeScript | @modelcontextprotocol/sdk | Intégration Cursor/Claude rapide ; wrappers autour de CLI Apple |
| Python | mcp | Pipelines data, transcription, indexation médias |
Le serveur minimal répond à initialize et enregistre un outil « echo ». Résultat attendu : une entrée visible dans la liste d'outils du Host.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });
server.tool(
"echo",
{ message: z.string().describe("Texte à renvoyer") },
async ({ message }) => ({ content: [{ type: "text", text: message }] })
);
await server.connect(new StdioServerTransport());
// ~/.cursor/mcp.json
{
"mcpServers": {
"hello-mcp": {
"command": "node",
"args": ["/chemin/absolu/mcp-hello/dist/index.js"]
}
}
}
Validation : chemins absolus pour command/args ; redémarrer le Host après modification. Vérifier tools/list dans l'inspecteur MCP.
Les Tools exécutent des effets de bord. Chaque outil exige un nom unique, un schéma Zod/JSON et des effets documentés. Exemple : interroger le statut d'un projet créatif dans le CRM.
server.tool(
"get_project_status",
{
projectId: z.string().uuid(),
includeDeliverables: z.boolean().default(false),
},
async ({ projectId, includeDeliverables }) => {
const res = await fetch(`${process.env.CRM_BASE}/projects/${projectId}`);
const data = await res.json();
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
}
);
Les Resources fournissent des données en lecture. URIs stables : brand://guidelines/v2, kb://tutorial/color-grading.
server.resource(
"brand_guide",
"brand://guidelines/v2",
async (uri) => ({
contents: [{
uri: uri.href,
mimeType: "text/markdown",
text: await fs.readFile("./data/brand-guide.md", "utf8"),
}],
})
);
Les Prompts encapsulent des scénarios récurrents : revue colorimétrique, checklist livraison motion, triage incident. Ils économisent des tokens par rapport aux longs system prompts dans le Host — utile quand Final Cut, Logic ou Xcode partagent le même agent.
server.prompt(
"delivery_review",
{
project: z.string(),
format: z.enum(["prores", "h264", "dnxhd"]),
},
({ project, format }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `Revue livraison ${project} (${format}) : specs, safe zones, métadonnées, 3 points bloquants.`,
},
}],
})
);
Dès qu'une équipe créative partage le même serveur (monteurs à distance, développeurs iOS), passez en HTTP+SSE. Prévoyez TLS, reverse proxy et affinité de session.
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";
const app = express();
let transport;
app.get("/sse", async (req, res) => {
transport = new SSEServerTransport("/message", res);
await server.connect(transport);
});
app.post("/message", express.json(), (req, res) => transport.handlePostMessage(req, res));
app.listen(8787);
| Paramètre HTTP | Dev | Production |
|---|---|---|
| TLS | localhost OK | Terminaison nginx/Caddy, HSTS |
| Timeout 1er appel | 60 s | 30 s après prewarm |
| Auth | Optionnel | Bearer ou OAuth 2.1 au point d'entrée |
| Symptôme | Preuve à collecter | Action |
|---|---|---|
| Liste d'outils vide | Code sortie, stderr | Chemin absolu ; même utilisateur OS que le Host |
| Premier appel lent | Logs npm | Épingler versions ; prewarm image |
| Schéma rejeté | JSON-RPC -32602 | Comparer sortie tools/list |
| Timeout récurrent | CPU, FD | Tool lecture seule en A/B |
npx @modelcontextprotocol/inspector node dist/index.js # Attendu : initialize OK, tools/list >= 1, tools/call echo OK
EnvironmentFile explicite.mcp.json versionné.tools/call ; métriques p95 et sessions SSE actives.Combinez Resources (guides brand, tutos montage) avec un Tool semantic_search. Flux : le modèle liste les Resources, recherche, cite les URIs — réduit les hallucinations dans les workflows où la charte graphique et les specs techniques doivent rester alignées.
server.tool(
"semantic_search",
{ query: z.string().min(3), topK: z.number().int().max(10).default(5) },
async ({ query, topK }) => {
const hits = await index.search(query, topK);
return {
content: [{
type: "text",
text: hits.map(h => `${h.uri}\n${h.snippet}`).join("\n---\n"),
}],
};
}
);
npx -y non épinglé.Un MCP Server sur le Mac de développement est le bon point de départ pour un studio ou une équipe produit. Trois limites apparaissent vite : les connexions STDIO/SSE coupent en veille, les environnements divergent entre créatifs et développeurs, et les workflows agent multi-étapes (montage automatisé, builds Xcode en chaîne) exigent une disponibilité continue. Les VM génériques sans macOS natif compliquent l'accès aux outchains Apple et aux simulateurs.
Pour des MCP Servers et agents en production — notamment sur workflows créatifs Apple — un nœud MACCOME Mac mini M4 / M4 Pro dédié 7×24 est souvent plus fiable qu'un MacBook local. Tarifs : tarifs location Mac mini ; prise en main : centre d'aide.
Questions fréquentes
Python ou TypeScript pour mon premier MCP Server ?
TypeScript pour Cursor/Claude en STDIO ; Python pour pipelines data et médias. Choisissez selon la stack existante.
STDIO ou HTTP+SSE en production ?
STDIO en solo. HTTP+SSE dès partage d'équipe — TLS, affinité et auth centralisée obligatoires.
MCP et Agent Skills : quelle différence ?
Skills = paquets dans le Host ; MCP = protocole d'outils cross-host. Voir le guide Agent Skill.
Quel hébergement pour MCP en production ?
Évitez la veille du MacBook pour les sessions longues. MACCOME propose des nœuds M4/M4 Pro 7×24. Tarifs et centre d'aide.