Model Context Protocol (MCP)

3 min read

Model Context Protocol (MCP)

PgArachne natively supports the Model Context Protocol (MCP), an open standard that allows AI models (like Claude or Cursor) to safely access your data and functions as “tools”.

How does it work?

PgArachne acts directly as an MCP Server. Instead of writing a custom HTTP server for each project, just run PgArachne on top of your database. PgArachne automatically analyzes your allowed SQL functions and exposes them to AI clients via HTTP(S).

🛠️ SQL Functions as Tools

Any SQL function that is accessible across PgArachne’s JSON-RPC 2.0 endpoint automatically becomes a “tool” in the AI. The default behavior (calling pgarachne.allowed_schemas()) exposes functions stored in the api schema that the user has access to (GRANT EXECUTE). The LLM sees the function name, parameters, and description from SQL comments.

Connection Guide

1. Creating an API Token

For permanent AI connection, we recommend using a long-lived API token instead of a short-lived JWT. For security reasons, the token must be generated by an administrator (pgarachne_admin role):

-- Switch to the administrator role
SET ROLE pgarachne_admin;

-- Generate a new token for the proxy user role (e.g., 'app_user')
SELECT pgarachne.add_api_token('Claude Desktop', 'app_user');

Save the returned string; it will be used for authentication. The token is validated on every HTTP request regardless of expiration dates.

2. Claude Desktop

Add PgArachne to your Claude Desktop configuration (~/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"
      }
    }
  }
}

Note: HTTP(S) is required for the connection. The example uses the server-http npx bridge from Anthropic, which acts as an intermediary between standard MCP (stdio) and PgArachne (HTTP).

3. Cursor

In Cursor settings (Settings > MCP), add a new server communicating directly via HTTP (or using the bridge mentioned above if Cursor does not support native HTTP MCP servers in your version):

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

🌐 Public Accessibility (Ngrok)

If you are testing PgArachne locally and want to connect it to a web AI (outside local installations), your server must be publicly accessible on an HTTP(S) URL.

# Run ngrok for the HTTP PgArachne port (e.g., 8080)
ngrok http 8080

Then use the generated HTTPS address from Ngrok in the AI configuration.

Security

The MCP endpoint in PgArachne fully respects the established database rules:

Authentication: Every request to the HTTP endpoint requires a valid API token or JWT; otherwise, it is immediately rejected.
Authorization: The AI sees and can call only those functions from allowed schemas that the authenticated role has GRANT EXECUTE for.
RLS: Row-Level Security is fully active — the AI will only see the rows the specific role has access to.

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