Server MCP — Calíope

Su macOS, Calíope può fare da server Model Context Protocol (MCP): un client IA che gira sullo stesso Mac — Cursor, Claude Desktop, qualunque cosa parli MCP — chiede a Calíope di elencare database, descrivere tabelle ed eseguire query in sola lettura sulle connessioni che scegli di esporre. Questa pagina dice che cos’è quel server, cosa può fare un client attraverso di esso, cosa deve valere prima che risponda e come collegare un client. La tabella degli strumenti è generata dal codice che li serve.

Che cos’è

Un server HTTP dentro Calíope che parla JSON-RPC 2.0, versione di protocollo 2025-06-18, annunciata nell’header MCP-Protocol-Version. Ascolta solo su 127.0.0.1 — su questo Mac e da nessun’altra parte — sulla porta 41500 a meno che tu non la cambi. La porta la scegli tu; l’indirizzo non è configurabile. Una sola rotta, POST /mcp, risponde a initialize, ping, tools/list e tools/call; un DELETE sulla stessa rotta chiude la sessione.

Esiste solo su macOS, è spento di fabbrica e risponde solo mentre Calíope è aperta: chiudi l’app e gli strumenti smettono di rispondere finché non la riapri. Se la porta scelta è già usata da un altro programma, Calíope te lo dice e non lo avvia.

Cosa può fare il client

Cinque strumenti, e nient’altro. La tabella qui sotto la scrive uno script a partire dall’array che il server serve in tools/list, e le descrizioni sono quelle che riceve il client, alla lettera — in inglese, qualunque sia la lingua di questa pagina —, perché quel testo è ciò che il modello dall’altra parte legge per decidere quale strumento chiamare. Tutti i parametri sono stringhe.

Strumento	Parametri	Descrizione
`list_connections`	—	Connections the user exposed to MCP. Returns id, name, engine, host.
`list_databases`	`connection`	Databases visible on a connection.
`list_tables`	`connection`, `database`	Tables and views in a database.
`describe_table`	`connection`, `database`, `table`	Columns, primary key, foreign keys and indexes of a table.
`run_query`	`connection`, `sql`	Run ONE read-only SQL statement (SELECT/SHOW/EXPLAIN/DESCRIBE) on a connection. Rows are capped at 200.

Dietro lo strumento che esegue SQL c’è una porta di sola lettura, che controlla l’istruzione prima che arrivi al server di database:

Un’istruzione per chiamata. Due istruzioni, o nessuna, vengono rifiutate.
Solo letture: SELECT, SHOW, EXPLAIN o DESCRIBE. Un INSERT, un UPDATE, un DROP, un WITH che finisce in una scrittura, o una lettura che scrive un file sul server vengono rifiutati.
Niente che prenda lock. SELECT … FOR UPDATE e LOCK IN SHARE MODE leggono, sì, ma tengono i lock fino alla fine della transazione, quindi vengono rifiutati anche loro.
Al massimo 200 righe. La risposta porta le colonne, le righe, il rowCount reale e truncated: true quando il limite ha tagliato qualcosa. Il limite non è configurabile.
Le connessioni MongoDB non vengono esposte. Non compaiono tra le connessioni che puoi spuntare, e gli strumenti rispondono che non sono disponibili via MCP.

Tutto ciò che viene eseguito via MCP finisce nel registro delle query di Calíope, con la connessione e il risultato, proprio come quello che digiti tu. Ciò che la porta rifiuta non arriva mai al server e non lascia alcuna riga.

Collegare un client

Accendi l’interruttore, spunta le connessioni, premi Copia configurazione, incolla nel suo file il blocco che serve al tuo client e riavvia il client. Negli appunti finiscono due blocchi con la tua porta e la tua chiave reali già dentro — gli stessi due che vedi qui con <port> e <token> come segnaposto.

Cursor legge un server HTTP direttamente. Il suo blocco va in ~/.cursor/mcp.json:

// Cursor — ~/.cursor/mcp.json
{
  "mcpServers": {
    "caliope": {
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Claude Desktop parla solo per input e output standard, non HTTP, quindi il suo blocco usa mcp-remote come ponte — è quello che fa npx lì. Va in ~/Library/Application Support/Claude/claude_desktop_config.json:

// Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "caliope": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:<port>/mcp",
               "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer <token>" }
    }
  }
}

I client leggono la loro configurazione all’avvio, quindi una chiave nuova o una porta nuova vogliono dire incollare di nuovo e riavviare.

Dove leggere di più

La guida ha tre argomenti su questo, e sono lo stesso testo che mostra l’app:

E Com’è fatta Calíope colloca il server accanto al resto dell’architettura.

Che cos’è

Cosa può fare il client

Consenso, connessione per connessione

Collegare un client

Dove leggere di più