Model Context Protocol (MCP)

3 min čtení

Model Context Protocol (MCP)

PgArachne nativně podporuje Model Context Protocol (MCP), otevřený standard, který umožňuje AI modelům (jako Claude nebo Cursor) bezpečně přistupovat k vašim datům a funkcím jako k „nástrojům" (tools).

Jak to funguje?

PgArachne funguje přímo jako MCP Server. Namísto psaní vlastního HTTP serveru pro každý projekt stačí PgArachne spustit nad vaší databází. PgArachne automaticky analyzuje vaše povolené SQL funkce a vystaví je AI klientům pomocí HTTP(S).

🛠️ SQL Funkce jako Nástroje

Jakákoli SQL funkce, která je dostupná přes JSON-RPC 2.0 endpoint PgArachne, se automaticky stane „nástrojem" v AI. Výchozí nastavení (volání pgarachne.allowed_schemas()) vystavuje funkce uložené ve schématu api, ke kterým má uživatel přístup (GRANT EXECUTE). LLM vidí název funkce, parametry a popis z SQL komentářů.

Průvodce připojením

1 a. Autentizace — API Token (doporučeno pro produkci)

Pro trvalé propojení s AI doporučujeme použít dlouhodobý API token. Z bezpečnostních důvodů musí token generovat administrátor (role pgarachne_admin):

-- Přepnutí do administrátorské role
SET ROLE pgarachne_admin;

-- Vygeneruje nový token pro cílovou roli (např. 'app_user')
SELECT pgarachne.add_api_token('Claude Desktop', 'app_user');

Poznamenejte si vrácený řetězec. Použijte jej jako Authorization: Bearer VÁŠ_API_TOKEN v konfiguraci AI klienta.

1 b. Autentizace — Přímé přihlášení (vývoj a jednoduché konfigurace)

Alternativně zasílejte PostgreSQL uživatelské jméno a heslo přímo pomocí HTTP Basic Authentication. Správa API tokenů není nutná a příkaz GRANT … TO pgarachne není vyžadován — PgArachne se připojuje přímo jako zadaný uživatel.

Authorization: Basic <base64(uzivatel:heslo)>

Tento přístup je vhodný pro lokální testování nebo interní nástroje, kde jsou přihlašovací údaje již bezpečně spravovány. Pro produkční integrace AI s cloudovými klienty jsou API tokeny preferovanou volbou.

2. Claude Desktop

Přidejte PgArachne do konfigurace 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 VÁŠ_API_TOKEN"
      }
    }
  }
}

Poznámka: Pro připojení je vyžadováno HTTP(S). Ukázka využívá npx bridge server-http od Anthropicu, který zprostředkuje komunikaci mezi standardním MCP (stdio) a PgArachne (HTTP).

3. Cursor

V nastavení Cursoru (Settings > MCP) přidejte nový server komunikující napřímo přes HTTP (nebo pomocí výše zmíněného bridge, pokud Cursor nativní HTTP MCP server nepodporuje ve vaší verzi):

Type: command (s npx bridge) nebo http
Name: PgArachne
URL: https://your-api.com/db/my_database/mcp
Auth Header: Authorization: Bearer VÁŠ_API_TOKEN

🌐 Veřejná dostupnost (Ngrok)

Pokud testujete PgArachne lokálně a chcete jej propojit s webovou AI (mimo lokální instalace), váš server musí být veřejně dostupný na HTTP(S) URL.

# Spusťte ngrok pro HTTP port PgArachne (např. 8080)
ngrok http 8080

V konfiguraci AI poté použijte vygenerovanou HTTPS adresu od Ngroku.

Bezpečnost

MCP endpoint v PgArachne plně respektuje nastavená pravidla databáze:

Autentizace: Každý požadavek na HTTP endpoint vyžaduje platný API token, JWT nebo HTTP Basic přihlašovací údaje; neověřené požadavky jsou okamžitě zamítnuty.
Autorizace: AI vidí a může volat jen ty funkce z povolených schémat, ke kterým má autentizovaná role GRANT EXECUTE.
RLS: Row-Level Security je plně aktivní — AI uvidí jen ty řádky, ke kterým má konkrétní role přístup.

Podrobné srovnání všech podporovaných metod autentizace naleznete v části Bezpečnost a autentizace.

← JSON-RPC (Hello World) Real-time notifikace (SSE) →

Model Context Protocol (MCP)