Expose AskDB as an agent tool

Integration · Agents

An agent asks AskDB for SQL through the same surfaces you use: the library, the HTTP API or the CLI. This guide wraps the library as a tool an agent can call. AskDB has no MCP server yet: the first-party one comes after 1.0 (mission).

Pick a surface

Surface	When to use it
CLI	Stable flags and structured logs. Good for scripted pipelines and CI.
Library	Embed `ask()` directly in your agent runtime — fastest path for Node agents. See Embed in a Node app.
HTTP API	`@askdb/http-api` for agents in any language. See Deploy as HTTP service.

The CLI and the HTTP API can’t serve a schema with a tenant policy yet: neither accepts a tenant scope (#277, #343). For a tenant-scoped agent tool, use the library.

All three surfaces use the same @askdb/core pipeline and run the same SQL checks, whichever you wrap. Those checks are heuristic defense in depth, not a security boundary. An agent can send any question it likes, so run the SQL it gets back under a read-only, least-privilege role. See Run generated SQL safely.

Wrap AskDB as a tool

A typical agent tool definition for AskDB looks like this:

import { createAskDb, type AskOverrides } from "@askdb/client";
import { bootstrapAskDbEnv, getAskDbRuntimeConfig } from "@askdb/config";

// Initialize once at startup — schema, model, and dialect resolve from config
// (install the @ai-sdk/* package for your ai.provider, e.g. @ai-sdk/openai).
bootstrapAskDbEnv({ cwd: process.cwd() });
const askdb = createAskDb({
  config: getAskDbRuntimeConfig(),
  schema: { path: "./my-app.schema" },
});

// Build the tool per request. The tenant scope comes from your host's auth
// context for this user, never from the agent's input.
export function askDatabaseTool(tenantScope?: AskOverrides["tenantScope"]) {
  return {
    name: "ask_database",
    description:
      "Translate a natural-language question into SQL against the application database. " +
      "Returns SQL; execution is the caller's responsibility.",
    parameters: {
      type: "object",
      properties: { question: { type: "string" } },
      required: ["question"],
    },
    async invoke({ question }: { question: string }) {
      const { sql, tenantParams } = await askdb.ask(question, { tenantScope });
      return { sql, tenantParams };
    },
  };
}

Adapt the object to your framework’s tool shape: Vercel AI SDK tools, OpenAI function calls, Anthropic tool use and other agent frameworks all take a name, a JSON Schema for the input, and a function. When your host runs the SQL, it runs sql with tenantParams ?? [].

To serve MCP clients such as Claude Desktop or Cursor before AskDB ships its own server, put this tool behind an MCP server in your host. It keeps the same rules as below: your host decides the schema, the mode and the sensitive-column setting, never the client.

Keep execution and scope in your host

Don’t let the agent run SQL. The tool returns checked SQL. Your application decides whether and how to run it, under a read-only, least-privilege role.
Take the tenant scope from your host. When the schema has a tenant policy, pass tenantScope from your host’s auth context, never from anything the agent or the user sent.

Expose AskDB as an agent tool

Pick a surface

Wrap AskDB as a tool

Keep execution and scope in your host

Read next