MCP tools#

MCP (Model Context Protocol) is a standard way for a server to advertise a set of callable tools. aidb.import_mcp_tools() registers an external MCP server and imports the tools it advertises, so your agents can call them alongside AIDB’s own native and SQL tools:

SELECT aidb.import_mcp_tools(
    name        => weather,
    url         => https://weather.example.com/mcp,
    transport   => streamable_http,  -- optional; streamable_http or sse (see below). Default: streamable_http
    headers     => NULL,               -- optional; request headers to send, for example, an auth token. Mutually exclusive with headers_env. Default: NULL
    tool_filter => NULL,               -- optional; import only these tool names. Default: NULL (import everything the server advertises)
    headers_env => NULL                -- optional; env var holding the headers JSON instead of storing it. Mutually exclusive with headers. Default: NULL
);

SELECT aidb.create_agent(trip_planner, Help plan trips, checking weather when useful., my_gpt,
    tools => ARRAY[get_forecast]);  -- a tool the weather server advertised

Parameter	Type	Default	Description
name	TEXT	Required	Unique name for the server registration.
url	TEXT	Required	The server's MCP endpoint URL.
transport	TEXT	'streamable_http'	'streamable_http' or 'sse' — only 'streamable_http' is fully supported today.
headers	JSONB	NULL	Request headers to send, for example, {"Authorization": "Bearer ..."}. Mutually exclusive with headers_env.
tool_filter	TEXT	NULL	Import only these tool names. Omit to import everything the server advertises.
headers_env	TEXT	NULL	Name of an environment variable holding the headers JSON, read fresh on each use instead of storing it. Mutually exclusive with headers.

import_mcp_tools validates the server by calling its tools/list endpoint before registering anything — if it’s unreachable or advertises nothing matching tool_filter , nothing is stored. The tools it returns are cached immediately, so they show up in aidb.tools right away rather than after a separate refresh.

Only the streamable_http transport (the default) actually works end-to-end today; sse is accepted as a value but isn’t fully implemented yet.

Reaching an MCP server is an outbound network call — subject to the same aidb.egress_allowlist restriction as model provider calls and HuggingFace downloads.

Authentication#

Pass headers for a server that needs specific request headers (most commonly an Authorization bearer token):

SELECT aidb.import_mcp_tools(
    name    => internal_crm,
    url     => https://crm.internal.example.com/mcp,
    headers => {"Authorization": "Bearer sk-..."}::JSONB
);

headers is stored in aidb.mcp_registry , but aidb_users has no SELECT access to that column — only AIDB’s own internal calls (to validate, refresh, or invoke the server’s tools) can read it back.

!!!note Prefer not to store the secret in the table at all? Pass headers_env instead: name an environment variable (read fresh from the Postgres process’s own environment on every call) holding a JSON object of headers, in the same shape headers would take. headers and headers_env are mutually exclusive. The variable’s name must start with the prefix configured by aidb.env_var_allowed_prefix (AIDB_ by default) — the same mechanism and GUC used by credentials_env for model credentials.

Filtering which tools are imported#

By default, every tool the server advertises is imported. Pass tool_filter to import only specific ones by name:

SELECT aidb.import_mcp_tools(
    name        => weather,
    url         => https://weather.example.com/mcp,
    tool_filter => ARRAY[get_forecast, get_alerts]
);

Keeping the tool list current#

AIDB doesn’t re-fetch a server’s tool list on every query — aidb.tools only shows entries cached within the last 60 minutes, so a SELECT never has a network side effect. Call aidb.refresh_mcp_tools() to re-fetch and update the cache on demand (for example, after the server adds a new tool):

SELECT aidb.refresh_mcp_tools(weather);

It returns the number of tools now cached (after tool_filter applies). Changing a server’s registration — its url , transport , headers , or tool_filter , via re-running import_mcp_tools -equivalent settings — also invalidates its cache automatically.

Removing a server#

SELECT aidb.delete_tool(weather);

Deleting an MCP server removes every tool it advertised along with it — there’s no way to remove just one of its tools individually; use tool_filter to curate which of its tools are exposed instead.

Exposing AIDB’s own tools over MCP#

aidb.get_mcp_tools() returns every tool currently in aidb.tools (native, SQL, and imported MCP tools alike), reshaped as MCP tools/list line items — useful if some other system needs AIDB’s tool catalog in MCP’s own descriptor format:

SELECT * FROM aidb.get_mcp_tools();

This only converts AIDB’s tool catalog into MCP’s descriptor shape — AIDB doesn’t run an MCP server endpoint of its own that an external MCP client could connect to and actually invoke these tools over the network.

MCP tools

Contents