Con l’adozione di MCP intro da parte dell’ecosistema AI, il passo successivo naturale e’ capire come estendere MCP oltre la macchina locale. MCP Connector e’ la feature dell’API Anthropic che ti permette di connettere Claude a server MCP remoti — via HTTP/SSE, con autenticazione, in produzione.
In questa guida vediamo come funziona concretamente: dalla differenza tra MCP locale e remoto, alla chiamata API con mcp_servers, fino ai pattern per gestire multi-server e sicurezza. Se usi gia’ Claude Code, sai gia’ quanto potenti sono i tool locali — ora portali in cloud.
MCP Locale vs MCP Remoto: Qual e’ la Differenza?
Il protocollo MCP nasce per connettere LLM a “context providers” — server che espongono tool, risorse e prompt strutturati. Nella versione locale, il server MCP gira sulla stessa macchina del client (tipicamente come processo figlio via stdio). E’ il caso classico di Claude Desktop o Claude Code.
Nella versione remota, il server MCP e’ un servizio HTTP accessibile via rete. La comunicazione avviene via HTTP con SSE (Server-Sent Events) per lo streaming, oppure via Streamable HTTP. Questo apre scenari completamente diversi:
- Team che condivide un MCP server centralizzato
- SaaS che espone le proprie funzionalita’ come MCP endpoint
- Integrazione Claude in pipeline backend senza dipendenze locali
- Multi-tenant: ogni cliente ha il suo server MCP isolato
💡 Chiave: MCP Connector non e’ un prodotto separato — e’ una sezione della chiamata API Anthropic che specifica server MCP remoti da usare durante la conversazione.
Configurare MCP Connector: La Struttura della Chiamata API
La chiave di tutto e’ il campo mcp_servers nel body della richiesta. Ecco la struttura base con Python SDK:
import anthropic
client = anthropic.Anthropic(api_key="YOUR_API_KEY")
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Cerca le ultime notizie su TypeScript 5 e riassumile"
}
],
mcp_servers=[
{
"type": "url",
"url": "https://your-mcp-server.com/mcp",
"name": "web-search",
"authorization_token": "Bearer YOUR_MCP_TOKEN"
}
],
betas=["mcp-client-2025-04-04"]
)
print(response.content)Lo stesso in TypeScript con fetch diretto:
const response = await fetch("https://api.anthropic.com/v1/messages", {
method: "POST",
headers: {
"x-api-key": process.env.ANTHROPIC_API_KEY!,
"anthropic-version": "2023-06-01",
"anthropic-beta": "mcp-client-2025-04-04",
"content-type": "application/json",
},
body: JSON.stringify({
model: "claude-opus-4-5",
max_tokens: 4096,
messages: [{ role: "user", content: "Elenca i file nel progetto" }],
mcp_servers: [
{
type: "url",
url: "https://your-mcp-server.com/mcp",
name: "filesystem-remote",
authorization_token: `Bearer ${process.env.MCP_TOKEN}`,
}
]
})
});
const data = await response.json();🔧 Beta header: MCP Connector richiede il header
anthropic-beta: mcp-client-2025-04-04. Senza di esso la chiamata ignora il campomcp_servers.
Gestire la Response con Tool Use Remoti
Quando Claude usa un tool MCP remoto, la response segue lo stesso pattern del tool use standard, ma i tool non sono dichiarati esplicitamente — vengono scoperti dinamicamente dal server MCP. La struttura della response:
import anthropic
client = anthropic.Anthropic(api_key="YOUR_API_KEY")
def run_mcp_conversation(user_message: str, mcp_url: str, mcp_token: str):
messages = [{"role": "user", "content": user_message}]
while True:
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=4096,
messages=messages,
mcp_servers=[{
"type": "url",
"url": mcp_url,
"name": "remote-tools",
"authorization_token": f"Bearer {mcp_token}"
}],
betas=["mcp-client-2025-04-04"]
)
# Se stop_reason e' "end_turn", abbiamo la risposta finale
if response.stop_reason == "end_turn":
return response.content[0].text
# Se stop_reason e' "tool_use", Claude sta usando un tool remoto
if response.stop_reason == "tool_use":
# Aggiungi la risposta di Claude ai messages
messages.append({
"role": "assistant",
"content": response.content
})
# MCP Connector gestisce il tool call automaticamente
# nella prossima iterazione Claude ricevera' il risultato
# Questo loop e' per tool locali — con MCP remoto
# Anthropic gestisce il round-trip al server MCP
break
return responseLa differenza fondamentale con i tool locali: con MCP remoto, Anthropic fa da proxy tra Claude e il server MCP. Claude chiede un tool, l’API Anthropic contatta il server MCP, ottiene il risultato e lo passa a Claude — tutto in modo trasparente.
Multi-Server MCP e Sicurezza
Puoi connettere piu’ server MCP nella stessa chiamata, ognuno con le proprie credenziali:
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=8096,
messages=[{"role": "user", "content": "Analizza il repo e cerca notizie correlate"}],
mcp_servers=[
{
"type": "url",
"url": "https://github-mcp.your-org.com/mcp",
"name": "github",
"authorization_token": f"Bearer {GITHUB_MCP_TOKEN}"
},
{
"type": "url",
"url": "https://search-mcp.your-org.com/mcp",
"name": "web-search",
"authorization_token": f"Bearer {SEARCH_MCP_TOKEN}"
},
{
"type": "url",
"url": "https://slack-mcp.your-org.com/mcp",
"name": "slack",
"authorization_token": f"Bearer {SLACK_MCP_TOKEN}"
}
],
betas=["mcp-client-2025-04-04"]
)
# Claude puo' orchestrare tutti e tre i server nella stessa conversazionePer la sicurezza, considera questi pattern:
# Pattern OAuth con token rotation
import os
from datetime import datetime, timedelta
class MCPTokenManager:
def __init__(self):
self.tokens = {}
self.expiry = {}
def get_token(self, server_name: str) -> str:
if self._is_expired(server_name):
self.tokens[server_name] = self._refresh_token(server_name)
self.expiry[server_name] = datetime.now() + timedelta(hours=1)
return self.tokens[server_name]
def _is_expired(self, server_name: str) -> bool:
if server_name not in self.expiry:
return True
return datetime.now() > self.expiry[server_name]
def _refresh_token(self, server_name: str) -> str:
# Implementa OAuth token refresh qui
# Es. client_credentials flow verso il tuo auth server
return f"refreshed_token_for_{server_name}"
token_manager = MCPTokenManager()
mcp_servers = [
{
"type": "url",
"url": "https://your-mcp.com/mcp",
"name": "secure-server",
"authorization_token": f"Bearer {token_manager.get_token('secure-server')}"
}
]🎯 Sicurezza: Non hardcodare mai i token MCP nel codice. Usa variabili d’ambiente, secret manager (AWS Secrets Manager, HashiCorp Vault) o il meccanismo OAuth del tuo identity provider. I token MCP hanno accesso a tutti i tool esposti dal server.
FAQ: MCP Connector — Domande Frequenti
Devo implementare il protocollo MCP sul mio server?
Si’. Il tuo server deve implementare le spec MCP (tool listing, tool call, resource management). Puoi usare gli SDK ufficiali: @modelcontextprotocol/sdk per Node.js o mcp per Python. Il server deve esporre un endpoint HTTP che risponde al protocollo MCP via SSE o Streamable HTTP.
C’e’ un costo aggiuntivo per MCP Connector?
MCP Connector non ha costi aggiuntivi oltre al normale pricing per token. I tool call remoti consumano token (per la descrizione dei tool e i risultati) come qualsiasi tool use. Considera che ogni round-trip al server MCP aggiunge latenza — progetta i tool per essere concisi nelle descrizioni e nei risultati.
Posso usare MCP Connector in produzione?
E’ in beta (header anthropic-beta richiesto) ma e’ stabile per produzione. Anthropic ha dichiarato che la API e’ pronta per deployment reali. Monitora il changelog Anthropic MCP Connector per aggiornamenti sulla GA release.
Quanto MCP locale differisce da MCP remoto nell’implementazione?
Il protocollo e’ identico — la differenza e’ nel trasporto. Locale usa stdio, remoto usa HTTP/SSE. Se hai gia’ un server MCP locale (es. per Claude Desktop), aggiungere un layer HTTP e’ relativamente semplice con gli SDK ufficiali. Il 90% del codice dei tool rimane invariato.
Come faccio debug di una chiamata MCP remota che non funziona?
Prima verifica che il server MCP risponda correttamente con curl diretto all’endpoint. Poi controlla i log della tua API Anthropic per eventuali errori nel campo mcp_servers. Un errore comune e’ il formato del token: deve essere il valore completo incluso il prefisso Bearer, o solo il token raw — dipende da come il tuo server lo valida.
