Agents and MCP

Integration · Agents

AskDB is built to be machine-driven. Agents can ground SQL generation through the same surfaces human integrators use — the CLI, the library, and the HTTP API. A first-party Model Context Protocol (MCP) server is roadmap work; for now, wrap one of the existing surfaces.

What works today

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.

All three surfaces use the same @askdb/core pipeline and enforce the same validator. Whichever you wrap, you get the same safety guarantees.

MCP status

A first-party Model Context Protocol server is planned. It will expose the same ask() contract through the MCP protocol so any MCP-aware agent (Claude Desktop, Cursor, IDE integrations) can call AskDB as a tool.

Until it ships, the recommended pattern is to write a thin MCP adapter in your own host that calls the HTTP API or the library directly. Your adapter enforces the same trust boundaries — modes, sensitive-field handling, which schema artifact is loaded — that the first-party MCP server will.

Track the roadmap on the AskDB GitHub project.

Wrapping AskDB as a tool

A typical agent tool definition for AskDB looks like:

import { createAskDb } from "@askdb/client";
import { bootstrapAskDbEnv, getAskDbRuntimeConfig } from "@askdb/config";
import { createAiRegistry } from "@askdb/ai";
import { openaiProvider } from "@askdb/ai-openai";

// Initialize once at startup — schema, model, and dialect resolve from config.
bootstrapAskDbEnv({ cwd: process.cwd() });
const askdb = createAskDb({
  config: getAskDbRuntimeConfig(),
  registry: createAiRegistry([openaiProvider]),
  schema: { path: "./my-app.schema" },
});

{
  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 }) {
    const { sql } = await askdb.ask(question);
    return { sql };
  },
}

This works in Vercel AI SDK tools, OpenAI function calls, Anthropic tool use, and any other agent framework that takes a function and a schema.

Trust in an agent loop

Two things matter when AskDB sits inside an agent:

1. The agent never executes SQL directly. It calls ask() and gets back validated SQL — your host code decides whether and how to run it.
2. The agent operates under a tenant scope you supply. When the schema has tenant policy, pass tenantScope from your host’s auth context — not from anything the agent (or the user) sent.

Read next

Embed in a Node appThe library surface you’ll most likely wrap in an agent tool.Deploy as HTTP serviceThe HTTP surface for non-Node agents.Safety boundariesWhat the validator enforces — same rules regardless of who’s asking.