MCP tools v7

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

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.

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.