Refresh with MCP

Skiff's MCP server exposes exactly one tool: refresh the DuckDB described by the repository's already-reviewed manifest and SQL. The caller cannot provide SQL, paths, source names, table names, or refresh bounds.

Start the server from the project

Run the process with the repository as its working directory and provide every password variable named in skiff.toml:

cd /path/to/data-project
export REPORTING_DB_PASS='...'
skiff mcp

Configure your MCP host with the absolute path to the skiff executable, the mcp argument, the project directory, and only the required environment variables. The exact configuration shape depends on the host.

The exposed tool

refresh() -> report

The tool takes no arguments and performs the same automatic refresh mode as skiff refresh. A successful report contains:

Field	Meaning
`generation`	Unique refresh identifier
`file`	Resolved DuckDB destination
`started_at`, `completed_at`	UTC timestamps
`elapsed_ms`	Total refresh duration
`rows`	Total rows in the published user tables
`tables`	Per-table source, loaded rows, total rows, and elapsed time
`schema_changes`	Advisory differences from the previously published schema

Errors are returned as structured text with message, changed, and human_action fields.

The plan is frozen at startup

Before accepting requests, the server discovers and validates skiff.toml, reads each query and check file, parses the source queries, and resolves paths. That plan remains in memory for the process lifetime; source credentials are resolved when a refresh runs.

Restart skiff mcp after a reviewed manifest, query, check, or credential-environment change. Editing a file while the server is running does not change the exposed refresh plan.

What an agent can and cannot do

Through this MCP server, an agent can:

trigger the fixed automatic refresh;
receive progress through the process logs;
inspect the returned row counts, timing, and schema-drift report.

It cannot:

submit or edit SQL through the tool;
select a different source, table, output, or repository;
request --full or a backfill window;
bypass the query, row, time, check, path, or publication rules.

MCP does not prevent an agent with separate shell or filesystem access from editing project files or invoking the CLI directly. Restrict those capabilities when the frozen plan is meant to be the boundary.

Handle concurrent refreshes

MCP does not queue behind another refresh. If the destination lock is held, the tool returns an error identifying the active refresh. Let that operation finish, then call the tool again.

Review the security model before giving an agent production credentials.