Model Context Protocol (MCP)

3 min czytania

Model Context Protocol (MCP)

PgArachne natywnie wspiera Model Context Protocol (MCP), otwarty standard, który pozwala modelom AI (takim jak Claude czy Cursor) bezpiecznie korzystać z Twoich danych i funkcji jako „narzędzi” (tools).

Jak to działa?

PgArachne działa bezpośrednio jako MCP Server. Zamiast pisać własny serwer HTTP dla każdego projektu, wystarczy uruchomić PgArachne nad swoją bazą danych. PgArachne automatycznie analizuje dozwolone funkcje SQL i udostępnia je klientom AI przez HTTP(S).

🛠️ Funkcje SQL jako narzędzia

Każda funkcja SQL dostępna przez endpoint JSON-RPC 2.0 PgArachne automatycznie staje się „narzędziem” dostępnym dla AI. Domyślne zachowanie (wywołanie pgarachne.allowed_schemas()) udostępnia funkcje przechowywane w schemacie api, do których uwierzytelniony użytkownik ma dostęp (poprzez GRANT EXECUTE). LLM widzi nazwę funkcji, parametry i opis pochodzący z komentarzy SQL.

Przewodnik połączenia

1 a. Uwierzytelnianie — token API (zalecane dla produkcji)

Do trwałego połączenia z AI użyj długoterminowego tokenu API. Token musi zostać wygenerowany przez administratora (członka roli pgarachne_admin):

-- Przełączenie na rolę administratora
SET ROLE pgarachne_admin;

-- Wygenerowanie nowego tokenu dla docelowej roli (np. 'app_user')
SELECT pgarachne.add_api_token('Claude Desktop', 'app_user');

Zapisz zwrócony ciąg znaków. Użyj go jako Authorization: Bearer YOUR_API_TOKEN w konfiguracji klienta AI.

1 b. Uwierzytelnianie — bezpośrednie dane logowania (rozwój i proste konfiguracje)

Alternatywnie możesz wysyłać nazwę użytkownika i hasło PostgreSQL bezpośrednio, używając HTTP Basic Authentication. Zarządzanie tokenami API nie jest wymagane, podobnie jak GRANT … TO pgarachne — PgArachne łączy się bezpośrednio jako podany użytkownik.

Authorization: Basic <base64(username:password)>

Użyj tego podejścia do lokalnych testów lub narzędzi wewnętrznych, w których dane logowania są już zarządzane w bezpieczny sposób. Dla produkcyjnych integracji AI z klientami chmurowymi preferowane są tokeny API.

2. Claude Desktop

Dodaj PgArachne do konfiguracji Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Uwaga: do połączenia wymagane jest HTTP(S). Przykład wykorzystuje mostek npx server-http od Anthropic, który działa jako pośrednik między standardowym MCP (stdio) a PgArachne (HTTP).

3. Cursor

W ustawieniach Cursor (Settings > MCP) dodaj nowy serwer komunikujący się bezpośrednio przez HTTP (lub korzystający z wymienionego wyżej mostka, jeśli Twoja wersja Cursor nie wspiera natywnych serwerów HTTP MCP):

Type: command (z mostkiem npx) lub http
Name: PgArachne
URL: https://your-api.com/db/my_database/mcp
Auth Header: Authorization: Bearer YOUR_API_TOKEN

🌐 Publiczna dostępność (Ngrok)

Jeśli testujesz PgArachne lokalnie i chcesz połączyć go z chmurowym klientem AI (poza lokalnymi instalacjami), Twój serwer musi być publicznie dostępny przez adres URL HTTP(S).

# Uruchom ngrok dla portu HTTP PgArachne (np. 8080)
ngrok http 8080

Następnie użyj wygenerowanego adresu HTTPS z Ngrok w konfiguracji AI.

Bezpieczeństwo

Endpoint MCP w pełni respektuje system uprawnień PostgreSQL:

Uwierzytelnianie: każde żądanie wymaga prawidłowego tokenu API, JWT lub danych logowania HTTP Basic; żądania nieuwierzytelnione są natychmiast odrzucane.
Autoryzacja: AI widzi i może wywoływać tylko te funkcje z dozwolonych schematów, do których uwierzytelniona rola ma GRANT EXECUTE.
RLS: Row-Level Security jest w pełni aktywne — AI widzi tylko te wiersze, do których dana rola ma dostęp.

Pełne porównanie wszystkich wspieranych metod uwierzytelniania znajdziesz w rozdziale Bezpieczeństwo i uwierzytelnianie.

← JSON-RPC (Hello World) Powiadomienia w czasie rzeczywistym (SSE) →

Model Context Protocol (MCP)