kozou mcp

kozou mcp starts a Model Context Protocol server backed by @kozou/mcp. It introspects the configured PostgreSQL database, builds a Schema Context from your DDL and COMMENT metadata, and serves it to AI agents (Claude Code, Claude Desktop, and other MCP clients) as a small set of read-only tools.

The server is a context provider, not a query engine. It hands agents the structure and meaning of your schema — table and view definitions, relations, and the business concepts you have annotated — so the agent can reason about your data and write its own SQL. The server itself never generates SQL, never executes it, and never writes to your database.

This page is the command reference. For end-to-end agent wiring (config file entries, client setup, and a working session), see Connect an MCP client.

Synopsis

kozou mcp [--stdio | --http] [--port <n>] [--host <host>] [--config <path>]

The server reads connection details (database URL, schemas, cache TTL) from kozou.config.yaml. See kozou.config.yaml for the full schema. The database is opened read-only; no migration is run and no row is written.

Transports

kozou mcp supports two transports. stdio is the default — if you pass neither --stdio nor --http, the server starts on stdio.

stdio (default)

kozou mcp --stdio

The stdio transport speaks MCP over standard input/output. This is the transport you want when an MCP client launches the server as a child process, which is how Claude Code and Claude Desktop connect. The client owns the process lifecycle, so there is no port or host to configure.

Because the bundled kozou.config.yaml template references the database URL as a ${DATABASE_URL} placeholder, you typically supply that variable in the environment that launches the command:

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  npx kozou mcp --stdio

The CLI expands ${DATABASE_URL} only because the config template references it; kozou does not read a KOZOU_DATABASE_URL variable directly.

HTTP

kozou mcp --http --port 3334 --host 127.0.0.1

The HTTP transport uses MCP’s Streamable HTTP transport and is meant for containerized or remote deployments, where the server runs as a long-lived process that clients reach over the network. It binds to 127.0.0.1 on port 3334 by default.

In HTTP mode the server also exposes a POST /admin/refresh endpoint that invalidates the in-memory Schema Context cache (see Caching).

Caution

The v0.1 HTTP server ships with no authentication. Keep it bound to 127.0.0.1 (the default). If you bind to a non-loopback host, anyone who can reach the port can call the tools. The tools return schema metadata only — they do not execute SQL or read row data — but treat the endpoint as you would any unauthenticated service.

Flags

Flag	Description	Default
--stdio	Serve MCP over the stdio transport.	enabled when no transport flag is given
--http	Serve MCP over the Streamable HTTP transport.	—
--port <n>	HTTP listen port (HTTP mode only).	3334
--host <host>	HTTP bind host (HTTP mode only).	127.0.0.1
--config <path>	Path to kozou.config.yaml.	resolved from the working directory

Tools

The server exposes six read-only tools. They map directly onto your schema and onto the concepts (database views) you have defined:

Tool	Input	What it returns
list_tables	optional schema, includeSystem	Tables in the schema with their label, description, and an estimated row count.
describe_table	qualifiedName (e.g. public.products)	Full schema for one table: columns, types, nullability, defaults, enum values, primary key, foreign-key relations, and check constraints — with any @ai notes from COMMENT.
list_views	optional schema	Views in the schema with their label and purpose.
describe_view	qualifiedName	A view’s columns, description, underlying tables, and SQL definition.
list_concepts	—	The business concepts in the schema. In v0.1 each concept is a database view.
get_concept_context	name	A concept’s @ai notes, a preferred query source, join suggestions, related tables, and any example queries declared via @example.

These tools surface the meaning you encode in COMMENT text. The @ai, @widget, @policy, and @example tags described in Comment conventions feed the aiDescription, aiNotes, and exampleQueries fields the tools return.

Read-only by design

There is intentionally no tool for generating, executing, or writing SQL. Underneath, introspection runs every query read-only. The agent receives context and composes its own queries against your data layer — PostgREST in v0.1, or the experimental in-house @kozou/api layer in the v0.2 line. The split between the read-only MCP surface and the data API is part of Kozou’s emitted surfaces model.

Errors

When a tool fails, it returns an MCP error result — isError: true with a text explanation rather than throwing. Stack traces are included only when the server runs with KOZOU_DEV=1.

Caching

The Schema Context is cached in process memory and never persisted to disk. It is invalidated by any of:

• HTTP mode — a POST /admin/refresh request.
• stdio mode — a SIGHUP signal to the process.
• TTL — after the cache TTL elapses (default 60 seconds; override with KOZOU_CACHE_TTL_MS or cache.ttlMs in kozou.config.yaml).

Refresh the cache after you change DDL or COMMENT text so agents see the updated schema without a restart.

Examples

Run the default stdio server, supplying the connection string in the environment:

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou mcp --stdio

Run an HTTP server on the default loopback address and port:

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou mcp --http --port 3334 --host 127.0.0.1

Invalidate the cache of a running HTTP server after editing a COMMENT:

curl -X POST http://127.0.0.1:3334/admin/refresh

Point the server at a config file outside the working directory:

kozou mcp --stdio --config ./config/kozou.config.yaml

A client calls a tool by name with a JSON argument object. For example, describe_table against a products table:

{
  "name": "describe_table",
  "arguments": { "qualifiedName": "public.products" }
}

Related

• Connect an MCP client — register kozou mcp with Claude Code or Claude Desktop and run a real session end to end.
• kozou dev — run the bundled Admin UI alongside an MCP HTTP server from a single command during development.
• kozou inspect — dump the same Schema Context the MCP tools serve, as JSON or YAML, for inspection or diffing.