Model Context Protocol (MCP)

3 min di lettura

Model Context Protocol (MCP)

PgArachne supporta nativamente il Model Context Protocol (MCP), uno standard aperto che consente ai modelli di intelligenza artificiale (come Claude o Cursor) di accedere in modo sicuro ai propri dati e funzioni come “strumenti”.

Come funziona?

PgArachne opera direttamente come server MCP. Invece di scrivere un server HTTP personalizzato per ogni progetto, è sufficiente eseguire PgArachne sul proprio database. PgArachne analizza automaticamente le funzioni SQL autorizzate e le espone ai client AI tramite HTTP(S).

Funzioni SQL come Strumenti

Qualsiasi funzione SQL accessibile tramite l’endpoint JSON-RPC 2.0 di PgArachne diventa automaticamente uno “strumento” disponibile per l’AI. Il comportamento predefinito (chiamata a pgarachne.allowed_schemas()) espone le funzioni memorizzate nello schema api a cui l’utente autenticato ha accesso (tramite GRANT EXECUTE). Il modello linguistico vede il nome della funzione, i parametri e la descrizione dai commenti SQL.

Guida alla Connessione

1 a. Autenticazione — Token API (consigliato per la produzione)

Per una connessione AI permanente, utilizza un token API a lunga durata. Il token deve essere generato da un amministratore (membro del ruolo pgarachne_admin):

-- Passa al ruolo amministratore
SET ROLE pgarachne_admin;

-- Genera un nuovo token per il ruolo di destinazione (es. 'app_user')
SELECT pgarachne.add_api_token('Claude Desktop', 'app_user');

Conserva la stringa restituita. Utilizzala come Authorization: Bearer IL_TUO_TOKEN_API nella configurazione del client AI.

1 b. Autenticazione — Credenziali dirette (sviluppo e configurazioni semplici)

In alternativa, è possibile trasmettere direttamente il nome utente e la password PostgreSQL tramite l’autenticazione HTTP Basic. Non è richiesta alcuna gestione di token API né alcun GRANT … TO pgarachne — PgArachne si connette direttamente come l’utente specificato.

Authorization: Basic <base64(utente:password)>

Questo approccio è adatto per test locali o strumenti interni in cui le credenziali sono già gestite in modo sicuro nell’ambiente. Per integrazioni AI di produzione con client cloud, i token API sono preferibili.

2. Claude Desktop

Aggiungi PgArachne alla configurazione di Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pgarachne": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http",
        "--url",
        "https://tua-api.com/db/my_database/mcp"
      ],
      "env": {
        "Authorization": "Bearer IL_TUO_TOKEN_API"
      }
    }
  }
}

Nota: è richiesto HTTP(S) per la connessione. L’esempio utilizza il bridge npx server-http di Anthropic, che funge da intermediario tra MCP standard (stdio) e PgArachne (HTTP).

3. Cursor

Nelle impostazioni di Cursor (Impostazioni > MCP), aggiungi un nuovo server che comunica direttamente tramite HTTP (oppure utilizza il bridge indicato sopra se la propria versione di Cursor non supporta server MCP HTTP nativi):

Tipo: command (con bridge npx) o http
Nome: PgArachne
URL: https://tua-api.com/db/my_database/mcp
Header Auth: Authorization: Bearer IL_TUO_TOKEN_API

Accessibilità pubblica (Ngrok)

Se si sta testando PgArachne in locale e si desidera connetterlo a un client AI basato su cloud (al di fuori delle installazioni locali), il server deve essere raggiungibile pubblicamente tramite un URL HTTP(S).

# Avvia ngrok sulla porta HTTP di PgArachne (es. 8080)
ngrok http 8080

Utilizza quindi l’indirizzo HTTPS generato da Ngrok nella configurazione AI.

Sicurezza

L’endpoint MCP rispetta pienamente il sistema di permessi di PostgreSQL:

Autenticazione: ogni richiesta richiede un token API valido, un JWT o credenziali HTTP Basic; le richieste non autenticate vengono rifiutate immediatamente.
Autorizzazione: l’AI può vedere e chiamare solo le funzioni negli schemi consentiti per cui il ruolo autenticato dispone di GRANT EXECUTE.
RLS: la Row-Level Security è pienamente attiva — l’AI vede solo le righe a cui il ruolo specifico ha accesso.

Consulta la pagina Sicurezza e Autenticazione per un confronto completo di tutti i metodi di autenticazione supportati.

← Esempio Hello World Strumenti →

Model Context Protocol (MCP)