Model Context Protocol (MCP) endpoint v7

The Model Context Protocol (MCP) endpoint lets agents outside the database call AIDB's tools over the Model Context Protocol. The MCP endpoint consists of an HTTP server, edb-endpoints, shipped in the AIDB package, and a Postgres background worker, known as the supervisor, that starts and supervises it. Every tool call runs as the Postgres role the agent authenticated with, so Postgres grants decide what each agent can run. By default the endpoint only accepts connections from the database host itself — see Serving remote clients to serve clients on other hosts.

Provisioning an agent is ordinary Postgres administration: create a login role, allow it in pg_hba.conf, and grant it the profile roles and tools it needs. See Configuring your agent role for what each of those steps involves, and Provisioning example for an end-to-end worked example that creates two agent roles with different grants and the tools they call.

How it works

The MCP endpoint has two components: edb-endpoints, an HTTP server that speaks MCP, and the supervisor, a Postgres background worker that starts it, restarts it if it exits, and shuts it down with Postgres.

Each request authenticates with a Postgres username and password, over its own database connection. By default the endpoint reaches Postgres through the server's Unix socket, falling back to TCP on 127.0.0.1 when no Unix socket is configured. Postgres grants decide what that agent can list and run, the endpoint itself has no separate permission system. Because every request connects fresh, current_user inside a tool is the agent's own role, and that role shows up in pg_stat_activity and the Postgres log like any other connection.

Postgres errors pass through to the client unchanged. A wrong password, a missing grant, or an unknown tool all surface as ordinary Postgres or MCP errors. See Connecting a client for the exact error text.

What tools the endpoint surfaces

The MCP endpoint provides two kinds of tools to every connected agent:

• The tool catalog: every tool in aidb.tools. tools/list shows what exists, not what the caller is allowed to run — Postgres decides that when the tool is actually called. Listing requires EXECUTE on aidb.get_mcp_tools(), which membership in aidb_users provides. A role without it gets the Postgres permission error as a tools/list error. There's no cache, so a tool registered with aidb.create_sql_tool() or aidb.import_mcp_tools() appears on the client's next tools/list. See Tools for the full catalog and how each kind of tool is registered.

• execute_sql, a built-in tool that lets an agent run any SQL statement directly, as itself, without registering a custom tool first. See Connecting a client for how to call it and what it returns.

Catalog tools and execute_sql share the same 10 MiB result cap. A larger result returns an error. See Result encoding for execute_sql for how each Postgres type is rendered.

You can register a tool named execute_sql, but the endpoint ignores it: the built-in keeps the name in both tools/list and tools/call, and the collision is logged. Duplicate catalog names keep their first row.

Documentation map