Il Model Context Protocol (MCP) è uno standard aperto che consente a modelli come quello di Anthropic Claude e strumenti per sviluppatori come Codice Claude richiamare strumenti esterni, fonti di dati e richieste in modo sicuro e standard.
Questa guida ti guiderà nella creazione del tuo server MCP partendo da zero, consentendo a Claude Code di accedere a funzionalità personalizzate e quindi di estendere notevolmente le sue funzionalità ben oltre quelle integrate.
Che cos'è il Model Context Protocol (MCP)?
MCP (Model Context Protocol) è un specifiche aperte Progettato per standardizzare il modo in cui i client basati su modelli linguistici (come Claude, Claude Code o altri frontend LLM) si connettono ai server degli strumenti e alle fonti dati. Si pensi a MCP come a una "porta USB-C per LLM": definisce uno schema di trasporto/JSON-RPC e un modo comune per i server di pubblicare tre tipi di funzionalità:
- Risorse — dati simili a file o documenti che un client può leggere (ad esempio, una riga del database, un file di testo, un payload JSON).
- Strumenti — funzioni richiamabili che il modello può chiedere all'host di eseguire (con l'approvazione dell'utente).
- Prompt — modelli di prompt o flussi di lavoro riutilizzabili che il modello/client può richiamare.
MCP supporta diversi tipi di trasporto (stdio, HTTP, SSE) e fornisce schema, SDK e server di esempio, in modo da non dover inventare autonomamente il formato wire. Il protocollo è gestito pubblicamente (spec + SDK) e offre tutorial e una galleria di server di esempio per accelerarne l'adozione.
Come è strutturato l'MCP?
L'architettura di MCP è volutamente semplice e modulare: i pezzi principali sono MCP server, MCP clientie trasporti che trasportano messaggi in frame JSON-RPC tra loro. Di seguito sono riportati i componenti principali con cui interagirai durante la creazione di un server per Claude Code (o altri client MCP).
Server, client e protocollo
- Server MCP — Un servizio che pubblica Strumenti, risorse e prompt. Gli strumenti possono eseguire effetti collaterali o recuperare dati; le risorse visualizzano contenuti di sola lettura; i prompt sono modelli di prompt riutilizzabili che il client può chiedere al modello di campionare.
- Client MCP (host) — In genere fa parte dell'host LLM (ad esempio, Claude Code, plugin VS Code, un client browser). Rileva i server disponibili, presenta le descrizioni degli strumenti al modello e indirizza le chiamate avviate dal modello ai server.
- Protocollo — I messaggi sono codificati come JSON-RPC; la specifica definisce gli eventi del ciclo di vita, la scoperta degli strumenti, l'invocazione, i completamenti/campionamenti e il modo in cui i risultati strutturati vengono trasferiti al client e al modello.
Modello di comunicazione (cosa succede quando si utilizza uno strumento)
- Il client invia un messaggio utente al modello.
- Il modello analizza il contesto e decide di chiamare uno strumento esposto da MCP (o più strumenti).
- Il client inoltra la chiamata allo strumento al server MCP tramite il trasporto scelto.
- Il server esegue lo strumento e restituisce i risultati.
- Il modello riceve l'output dello strumento e compone la risposta finale per l'utente.
Primitive di implementazione
- JSON-RPC i messaggi seguono lo schema MCP.
- Definizioni degli strumenti vengono pubblicati nelle risposte di individuazione del server in modo che i client possano presentarli nell'interfaccia utente.
- Risorse sono referenziati da
@source:pathsintassi da parte dei clienti (ad esempio,@postgres:...), consentendo ai modelli di fare riferimento a contenuti esterni senza dover incorporare enormi quantità di dati nel prompt.
Perché integrare Claude Code con i server MCP?
Claude Code è l'offerta di Anthropic focalizzata su flussi di lavoro incentrati sul codice e sugli sviluppatori (integrazione editor/IDE, comprensione del codice, ecc.). L'esposizione dei tuoi strumenti interni (ricerca di codice sorgente, runner CI, sistema di ticket, registri privati) tramite server MCP consente a Claude Code di chiamarli come strumenti di prima classe all'interno delle conversazioni di codifica e dei flussi degli agenti.
L'integrazione di Claude Code con i server MCP sblocca funzionalità pratiche e rilevanti per la produzione per un agente di codifica:
1. Lascia che il modello agire su sistemi reali
Claude Code può chiedere a un server MCP di interrogare gli issue tracker, eseguire query sul database, leggere documenti di grandi dimensioni o produrre PR GitHub, consentendo l'automazione end-to-end direttamente dalla sessione di programmazione. Questa funzionalità è supportata esplicitamente dalla documentazione di Claude Code (ad esempio, interrogare PostgreSQL, Sentry o creare PR).
2. Scaricare grandi quantità di dati e logica specializzata
Invece di incorporare ogni fonte dati nel prompt (che consuma token), si pubblicano dati e strumenti tramite MCP. Il modello richiama lo strumento, riceve una risposta strutturata e la utilizza per ragionare: questo riduce l'utilizzo dei token e consente ai server di gestire attività pesanti (query al database, letture di file lunghi, autenticazione).
3. Sicurezza e governance
MCP centralizza il controllo degli accessi e l'audit a livello server, consentendo alle organizzazioni di inserire nella whitelist i server approvati, controllare quali strumenti sono disponibili e limitare gli output. Claude Code supporta anche la configurazione MCP aziendale e il consenso per ambito.
4. Riutilizzabilità ed ecosistema
I server MCP sono riutilizzabili tra client e team. Una volta compilati, molti client Claude/LLM possono utilizzare gli stessi servizi (o scambiare le implementazioni).
Di cosa hai bisogno prima di iniziare?
Requisiti minimi
- Una macchina di sviluppo con Pitone 3.10+ (nell'esempio useremo Python). In alternativa, Node/altri linguaggi sono supportati dagli SDK MCP.
uv(strumento di Astral) o un runner equivalente per l'esecuzione di server MCP stdio (il tutorial MCP utilizzauv). Di seguito sono riportati i passaggi di installazione.- Claude Code installato o accesso al client Claude (desktop o CLI) per registrare e testare il server; oppure qualsiasi client compatibile con MCP. Claude Code supporta server HTTP, SSE e stdio locali.
- Nota di sicurezza: Aggiungi server MCP attendibili a Claude Code solo in impostazioni aziendali o di team: MCP consente ai server di accedere a dati sensibili e sussistono rischi di iniezione immediata se un server restituisce contenuti dannosi.
Come installare e verificare la CLI di Claude Code
Questo è anche Guida all'installazione e all'uso del codice Claude.
1) Riepilogo rapido: metodi di installazione consigliati
Usa il programma di installazione nativo (consigliato) o Homebrew su macOS/Linux. NPM è disponibile se hai bisogno di un'installazione basata su Node. Windows dispone di programmi di installazione PowerShell/CMD. Fonte: documentazione ufficiale di Claude Code e GitHub.
2) Prerequisiti
- macOS 10.15+, Ubuntu 20.04+/Debian 10+ o Windows 10+ (WSL consigliato su Windows).
- Node.js 18+ solo richiesto per il metodo di installazione NPM.
3) Comandi di installazione (scegline uno)
Nativo (consigliato, nessuna dipendenza da Node), macOS / Linux / WSL:
curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest
(Questi sono gli script di installazione nativi ufficiali).
NPM (se si desidera un'installazione globale basata su Node):
# requires Node.js 18+
npm install -g @anthropic-ai/claude-code
Non uso sudo npm install -g — avverte contro le installazioni globali sudo (problemi di autorizzazione/sicurezza). Se si verificano errori di autorizzazione, utilizzare nvm oppure correggi il prefisso globale npm anziché usare sudo.
4) Verificare che il binario sia stato installato (controlli di base)
Eseguirli localmente subito dopo l'installazione:
# is the command on PATH?
which claude
# version (or -v)
claude --version
# or
claude -v
# help (sanity check)
claude --help
Previsto: which mostra un percorso (ad esempio /usr/local/bin/claude or ~/.nvm/.../bin/claude) e claude --version stampa una stringa simile a semver. Sia la documentazione che il file README mostrano claude come punto di ingresso CLI primario.
5) Verificare lo stato di integrità e la configurazione dell'installazione (controlli consigliati)
a) claude doctor,Correre:
claude doctor
Questa diagnostica integrata controlla il tipo di installazione, i problemi comuni (come i problemi di autorizzazione npm), le dipendenze come ripgrepe suggerisce soluzioni. La documentazione raccomanda esplicitamente di eseguire claude doctor dopo l'installazione.
b) Eseguire un test del fumo (non interattivo)
Dalla directory del tuo progetto:
cd /path/to/your/project
claude -p "Explain this project in 3 sentences"
Questo utilizza stampare modalità (-p) per inviare un singolo prompt e poi uscire; utile per CI o rapidi controlli funzionali.
c) Verifica dell'autenticazione (assicurarsi che la CLI possa raggiungere Anthropic)
Claude Code supporta diversi flussi di autenticazione (OAuth della console, chiave API, integrazioni con provider). Controlli comuni:
- Se si utilizza una chiave API (CI / headless / variabile di ambiente locale):
export ANTHROPIC_API_KEY="sk-..."
# then
claude auth status
claude auth whoami # or `claude auth whoami` / `claude whoami` depending on version
Puoi usare CometaAPIChiave API di per utilizzare Claude Code. Utilizzando l'API di Claude tramite CometAPI otterrai uno sconto del 20%.
- Se hai utilizzato OAuth tramite la console - correre:
claude auth status
claude auth whoami
Dovresti vedere le informazioni sull'account/piano o una conferma che sei autenticato.
Preparazione dell'ambiente passo dopo passo
Di seguito sono riportati i passaggi concreti per preparare due stack di sviluppo comuni (TypeScript e Python), seguiti da rapidi controlli per garantire che tutto funzioni.
H3 — A. Configurazione TypeScript/Node (percorso più veloce)
- Crea il progetto e installa l'SDK:
mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express
- Crea
server.ts(Forniamo un esempio completo nella sezione "Come creare rapidamente...".) - Esegui:
npx -y tsx server.ts
- Prova localmente con il Ispettore MCP oppure aggiungi al Codice Claude:
npx @modelcontextprotocol/inspector
# or (for Claude Code)
claude mcp add --transport http my-server http://localhost:3000/mcp
(I comandi Inspector e Claude consentono di convalidare la scoperta e richiamare gli strumenti.)
Come creare rapidamente un server MCP per Claude Code?
rapida lista di controllo
-
Avvia il tuo server (si consiglia HTTP Streamable):
node server.tsoruvicorn server:app. -
Dalla tua macchina di sviluppo, puoi:
- Usa il Ispettore MCP per convalidare (
npx @modelcontextprotocol/inspector) e confermaretools/liste alresources/listOppure - Aggiungi il server al codice Claude:
claude mcp add --transport http <name> http://<host>:<port>/mcp(oppure seguire i flussi dell'interfaccia utente Web se il client supporta MCP remoto).
Se intendi utilizzare il connettore API Messaggi di Anthropic per MCP remoto (nessun client separato), leggi la documentazione di Claude: potrebbe essere necessaria un'intestazione beta (controlla la documentazione per l'intestazione esatta e lo stato attuale del supporto).
Di seguito sono riportati due esempi di server completi ma compatti che è possibile copiare, eseguire e connettere a Claude Code (o a MCP Inspector). L'esempio TypeScript utilizza Express + TypeScript SDK; l'esempio Python illustra un montaggio FastAPI.
Nota: il codice seguente segue gli esempi pubblici dell'SDK ed è volutamente minimale per chiarezza. Per la produzione, aggiungere autenticazione, registrazione, limitazione della velocità e convalida dell'input oltre alle impostazioni predefinite dell'SDK.
Esempio 1: TypeScript + Express (HTTP trasmissibile)
Crea
server.ts (completare):
// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });
// Register a simple tool: add two numbers
server.registerTool(
"add",
{
title: "Add",
description: "Add two numbers a and b",
inputSchema: { a: z.number(), b: z.number() },
outputSchema: { result: z.number() }
},
async ({ a, b }) => {
const output = { result: a + b };
return {
content: ,
structuredContent: output
};
}
);
// Register a resource: greet user (dynamic)
server.registerResource(
"greeting",
new ResourceTemplate("greeting://{name}", { list: undefined }),
{ title: "Greeting", description: "Return a greeting for the name" },
async (uri, params) => {
return {
contents:
};
}
);
// Express + Streamable HTTP transport
const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
// Close transport when connection closes
res.on("close", () => transport.close());
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});
const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));
Esegui:
npm install
npx -y tsx server.ts
Quindi collega in Claude Code (esempio):
# Add the remote server to your Claude Code MCP list (local dev)
claude mcp add --transport http my-demo http://localhost:3000/mcp
Questo esempio è adattato dal Quick Start ufficiale di TypeScript SDK e mostra come registrare strumenti e risorse, per poi esporli tramite Streamable HTTP.
Esempio 2: Python + FastAPI (FastMCP + HTTP Streamable)
Crea
server.py (completare):
# server.py
from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP
app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)
# tool: simple sum
@mcp.tool()
def add(a: int, b: int) -> dict:
"""Add two integers"""
return {"result": a + b}
# resource: simple greeting resource template
@mcp.resource("greeting://{name}")
def greeting(name: str):
return {"contents": }
# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)
app.mount("/mcp", mcp.streamable_http_app())
# optional endpoint to demonstrate other API routes
@app.get("/")
async def root():
return {"status": "OK"}
Esegui:
uvicorn server:app --reload --port 8000
Contatta l'ispettore:
npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp
Gli esempi di Python SDK e le utilità FastMCP semplificano la registrazione @mcp.tool() e al @mcp.resource() funzioni decorate che l'LLM può scoprire e chiamare.
Come chiama effettivamente i tuoi strumenti Claude Code?
Quando un LLM decide di utilizzare uno strumento, il client invia un'invocazione JSON-RPC al server MCP. Il server esegue lo strumento richiesto (ad esempio, interroga un database, esegue test o chiama un'API esterna) e restituisce contenuto strutturato e al contenuto presentabileIl client (Claude Code) può quindi includere l'output strutturato nel contesto del modello in modo che il modello possa continuare a ragionare con quei dati affidabili, non solo con l'output testuale del server. L'SDK TypeScript supporta la registrazione inputSchema e al outputSchema (zod) quindi gli argomenti e gli output vengono convalidati e tipizzati dalla macchina.
Quali strumenti di test e debug dovresti utilizzare?
Ispettore MCP
. Ispettore MCP è lo strumento di sviluppo visuale ufficiale per testare i server MCP. Permette di connettersi a un server (stdio, SSE o streamable-HTTP), elencare gli strumenti, invocarli manualmente e ispezionare il ciclo di vita dei messaggi JSON-RPC, un valore inestimabile durante lo sviluppo. Avvialo tramite npx @modelcontextprotocol/inspector.
Test locali vs test remoti
- Locale (stdio) — ciclo di iterazione rapido per app desktop e debug offline.
- HTTP trasmissibile in streaming — testare con l'Inspector o connettersi a Claude Code utilizzando
claude mcp addCLI o il connettore MCP nell'API Messaggi per i test remoti. Assicurati di fornire tutte le intestazioni di autenticazione richieste per il tuo server.
Conclusione
MCP rappresenta il ponte pratico tra i moderni LLM e i sistemi che effettivamente contengono i dati ed eseguono le azioni. Per i flussi di lavoro del codice, l'integrazione di Claude Code con un server MCP fornisce al modello un accesso strutturato e verificabile a repository, CI, issue tracker e strumenti personalizzati, con conseguente automazione più precisa ed effetti collaterali più sicuri. Con SDK ufficiali in TypeScript e Python, HTTP Streamable per l'hosting remoto e strumenti come MCP Inspector, è possibile creare un server minimale in pochi minuti e iterare verso una distribuzione di produzione.
Gli sviluppatori possono accedere Claude Sonetto 4.5 API e al API di Claude Opus 4.1 ecc. tramite CometAPI, l'ultima versione del modello è sempre aggiornato con il sito ufficiale. Per iniziare, esplora le capacità del modello nel Parco giochi e consultare il Guida API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l'accesso a CometAPI e di aver ottenuto la chiave API. CometaAPI offrire un prezzo molto più basso rispetto al prezzo ufficiale per aiutarti a integrarti.
Pronti a partire? → Iscriviti oggi a CometAPI !
Se vuoi conoscere altri suggerimenti, guide e novità sull'IA seguici su VK, X e al Discordia!