Connect an AI agent over MCP

Kozou ships an MCP server that exposes your PostgreSQL schema as structured context for AI agents. Once connected, an agent such as Claude Code or Claude Desktop can read what your tables, views, and business concepts mean — the descriptions, @ai notes, and example queries you wrote in COMMENT — through six read-only tools.

This page covers both transports: stdio, for a local agent that launches the server itself, and HTTP, for Docker or remote use. For the command reference, see kozou mcp. For what each tool returns, see The three surfaces.

Before you start

You need a Kozou project with a reachable PostgreSQL database. The server reads a DATABASE_URL connection string — the same one the rest of the CLI uses, expanded into kozou.config.yaml through its ${DATABASE_URL} placeholder. A generic connection string looks like:

postgres://USER:PASSWORD@HOST:5432/DBNAME

You do not need to write any application code. The server reads your schema and COMMENT text and serves them as-is.

The stdio path: Claude Code and Claude Desktop

For a local agent, register kozou mcp --stdio as an MCP server in the client’s config. The agent spawns the process on demand and talks to it over standard input/output — nothing listens on a port.

Add an entry under mcpServers. This shape works for any MCP client that follows the standard config format (Claude Code and Claude Desktop both do):

{
  "mcpServers": {
    "kozou": {
      "command": "npx",
      "args": ["-y", "kozou", "mcp", "--stdio"],
      "env": {
        "DATABASE_URL": "postgres://USER:PASSWORD@HOST:5432/DBNAME"
      }
    }
  }
}

A few notes on this entry:

• npx -y kozou mcp --stdio runs the published kozou package without a global install; the -y skips the install prompt. If you have already installed kozou globally, you can set "command": "kozou" and drop "kozou" from args.
• DATABASE_URL is read by the bundled CLI through the ${DATABASE_URL} placeholder in kozou.config.yaml. Set it in the env block as shown rather than relying on the client’s ambient environment.
• stdio is the default transport, so --stdio is explicit but matches the default. The server installs a SIGHUP handler that refreshes its cached schema, so a long-lived process can pick up DDL or COMMENT changes without a restart.

Restart the client after editing the config. The six tools then appear to the agent under the kozou server name.

The HTTP path: Docker and remote

For a containerized or remote setup, run the server over HTTP instead. This is the transport a standard MCP client speaks when it connects to a URL rather than launching a process:

DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/DBNAME \
  npx kozou mcp --http --port 3334

The HTTP server listens on port 3334 by default and serves the MCP endpoint at /mcp. It also exposes POST /admin/refresh, the HTTP-mode counterpart to the stdio SIGHUP handler, which invalidates the cached schema so the next request re-reads your database.

kozou dev brings up this same HTTP server alongside the Admin UI — the UI on port 3333 and the MCP HTTP server on 3334 — wired from kozou.config.yaml. If you are already running kozou dev, the MCP endpoint is live at http://localhost:3334/mcp without a separate command. See kozou dev and Generate an Admin UI.

Binding and exposure

By default the HTTP server binds to 127.0.0.1 (loopback only). You can change the listener with --host and --port:

Flag	Default	What it does
--port <n>	3334	TCP port the HTTP server listens on.
--host <addr>	127.0.0.1	Interface to bind.

In v0.1.1 the MCP HTTP transport ships with no authentication. If you bind to a non-loopback host, the server prints a loud warning: anyone who can reach that address can read the database’s schema metadata. The tools only expose schema metadata — no SQL execution and no data access, which bounds the blast radius — but you should still keep the server on loopback unless it sits behind a trusted network and an external auth/proxy layer.

What the agent can do once connected

The server exposes six tools, all read-only context providers:

Tool	Returns
list_tables	Table names with their labels, descriptions, and a planner row-count estimate.
describe_table	The full schema and COMMENT for one table: columns, types, nullability, primary key, foreign-key relations, and check constraints.
list_views	View names with their labels and purposes.
describe_view	A view’s columns, purpose, the tables it depends on, and its SQL definition.
list_concepts	The domain concepts, each backed by a view.
get_concept_context	A concept’s related tables, a preferred query source, join suggestions, and example queries.

With these, an agent reads not just the shape of your schema but its meaning — and the recommended way to query it. describe_table, describe_view, and get_concept_context each carry the AI-facing notes you wrote with the @ai tag, so guidance like “for revenue figures, prefer the view vw_orders_paid” reaches the agent directly. Example queries written with @example surface through get_concept_context as a list of { description, sql } entries — the recommended query paths for a concept. (For how those tags are parsed, see COMMENT conventions.)

For example, an agent asked about an orders table calls describe_table to learn its columns and foreign keys, then get_concept_context on a paid-orders concept to find the suggested FROM source and an example revenue query — all without you pasting any schema into the prompt.

The read-only safety boundary

None of the six tools generate SQL, execute SQL, or write data. They return schema metadata and COMMENT text and nothing else. An agent connected to Kozou over MCP can read what your schema means but cannot mutate your data through this surface — there is no write path in the tool set, on either transport.

This is also why the HTTP server can bind to loopback and warn loudly off it: the worst case for an exposed MCP endpoint is disclosure of schema metadata, not data loss. If your agent needs to read or write rows, that belongs to a separate surface — the REST API (PostgREST in v0.1.1, or the experimental in-house @kozou/api behind kozou dev --adapter api in the v0.2 line) — not to MCP.

Where to next

• kozou mcp — the command reference: flags, transports, and the refresh endpoint.
• COMMENT conventions — how @ai, @example, and the other tags shape what the agent sees.
• The three surfaces — how MCP context fits alongside the Admin UI and the REST API.