Créer un Serveur MCP pour Claude Code : Le Guide Complet

// Le flux de communication MCP
Claude Code → JSON-RPC Request → /api/mcp
                                    ↓
                            Authentification
                                    ↓
                            Tool Selection
                                    ↓
                            Action Execution
                                    ↓
Claude Code ← JSON-RPC Response ←──┘

// Exemple de prompt structuré pour générer l'app
"Créer une application Todo complète de type Kanban avec :
- Authentification email/mot de passe
- Drag and drop pour les colonnes
- Mise à jour temps réel via SSE
- Page /settings pour gérer les clés API
- Style moderne avec Shadcn/ui

Stack : Next.js 14, MongoDB, NextAuth.js"

import { createHash } from 'crypto';
import { ApiKey } from '@/models/ApiKey';

export async function authenticateMCP(request: Request): Promise {
  const apiKey = request.headers.get('x-api-key');
  
  if (!apiKey) return null;
  
  // Hash SHA-256 de la clé (jamais stockée en clair)
  const hashedKey = createHash('sha256').update(apiKey).digest('hex');
  
  const keyDoc = await ApiKey.findOneAndUpdate(
    { keyHash: hashedKey },
    { $set: { lastUsedAt: new Date() } }
  );
  
  return keyDoc ? keyDoc.userId : null;
}

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export function registerTodoTools(server: McpServer, userId: string) {
  
  // Tool: Lister les tâches
  server.tool('list_todos', 
    'Liste toutes les tâches de l\'utilisateur avec filtres optionnels',
    {
      status: z.enum(['todo', 'in_progress', 'done']).optional(),
      priority: z.enum(['low', 'medium', 'high']).optional(),
      search: z.string().optional()
    },
    async ({ status, priority, search }) => {
      const filter: any = { userId };
      if (status) filter.status = status;
      if (priority) filter.priority = priority;
      if (search) filter.title = { $regex: search, $options: 'i' };
      
      const todos = await Todo.find(filter);
      return { content: [{ type: 'text', text: JSON.stringify(todos) }] };
    }
  );

  // Tool: Créer une tâche
  server.tool('create_todo',
    'Crée une nouvelle tâche',
    {
      title: z.string(),
      priority: z.enum(['low', 'medium', 'high']).default('medium')
    },
    async ({ title, priority }) => {
      const todo = await Todo.create({
        userId, title, priority, status: 'todo'
      });
      emitChange(userId); // SSE notification
      return { content: [{ type: 'text', text: JSON.stringify(todo) }] };
    }
  );

  // Tool: Déplacer une tâche
  server.tool('move_todo',
    'Déplace une tâche vers une autre colonne',
    {
      todoId: z.string(),
      newStatus: z.enum(['todo', 'in_progress', 'done'])
    },
    async ({ todoId, newStatus }) => {
      await Todo.findByIdAndUpdate(todoId, { status: newStatus });
      emitChange(userId);
      return { content: [{ type: 'text', text: 'Tâche déplacée' }] };
    }
  );

  // Tool: Supprimer une tâche
  server.tool('delete_todo',
    'Supprime une tâche de manière permanente',
    { todoId: z.string() },
    async ({ todoId }) => {
      const todo = await Todo.findById(todoId);
      if (!todo || todo.userId !== userId) {
        throw new Error('Tâche non trouvée');
      }
      await Todo.findByIdAndDelete(todoId);
      emitChange(userId);
      return { content: [{ type: 'text', text: 'Tâche supprimée' }] };
    }
  );
}

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerTodoTools } from './tools/todo';

export function createMCPServer(userId: string): McpServer {
  const server = new McpServer({
    name: 'todo-mcp',
    version: '1.0.0'
  });
  
  // Enregistrer les tools
  registerTodoTools(server, userId);
  
  // Ajouter d'autres modules ici au besoin
  // registerClientTools(server, userId);
  // registerCalendarTools(server, userId);
  
  return server;
}

import { authenticateMCP } from '@/lib/mcp/auth';
import { createMCPServer } from '@/lib/mcp/factory';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

export async function POST(request: Request) {
  // 1. Authentification
  const userId = await authenticateMCP(request);
  if (!userId) {
    return new Response('Non autorisé', { status: 401 });
  }
  
  // 2. Créer le serveur MCP pour cet utilisateur
  const server = createMCPServer(userId);
  
  // 3. Connecter le transport HTTP
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined
  });
  await server.connect(transport);
  
  // 4. Traiter la requête
  const response = await transport.handleRequest(request);
  
  return response;
}

export async function GET(request: Request) {
  // Même logique pour les requêtes GET (découverte)
  // ...
}

export async function DELETE(request: Request) {
  // Fermeture propre des sessions MCP
  // ...
}

claude mcp add todo-mcp \
  --transport http \
  --url http://localhost:3000/api/mcp \
  --header x-api-key: YOUR_API_KEY_HERE

> /mcp

MCP Servers:
  todo-mcp ● Connected
    Tools: list_todos, create_todo, move_todo, delete_todo