ovstorage-user-connect-via-mcp

Use when connecting an agent client to ovstorage over MCP stdio and mapping common CLI workflows to MCP tools.

SKILL.md

GitHub

Connect Via MCP

Goal: Configure an agent client to spawn ovstorage-mcp, verify the configured backends, then choose the MCP tool that matches the user's storage task.

Server configuration

Register ovstorage-mcp as an MCP stdio server. Pass the same config and plugin environment you would use with the CLI:

{
  "command": "ovstorage-mcp",
  "env": {
    "OVSTORAGE_CONFIG": "/path/to/ovstorage.toml",
    "OVSTORAGE_PLUGIN_DIR": "/path/to/plugins"
  }
}

OVSTORAGE_CONFIG follows CLI precedence. If you intentionally want a programmatic/no-config session, set OVSTORAGE_MCP_NO_CONFIG=1.

First call

Call ovstorage_doctor before object I/O:

{
  "tool": "ovstorage_doctor",
  "arguments": {}
}

Confirm the desired backend kind is among the layers this stack declares, and that the target address root is visible, before calling read/write/list tools. A kind absent from backend_kinds is a kind this stack's config never declared a layer for.

MCP to CLI equivalence

MCP tool Closest CLI command Notes
ovstorage_doctor ovstorage doctor --json Health/config summary for agents.
ovstorage_capabilities ovstorage list-backends plus ovstorage list-routes MCP reports one prefix.
ovstorage_stat ovstorage stat ADDRESS Object info.
ovstorage_list ovstorage list PREFIX Use next_page_token for pagination.
ovstorage_read ovstorage read ADDRESS Requires max_bytes; bytes are base64.
ovstorage_materialize ovstorage read ADDRESS -o FILE MCP returns a leased path, not a durable caller-owned copy.
ovstorage_release none Releases a materialize lease.
ovstorage_write ovstorage write ADDRESS Data is base64 in MCP.
ovstorage_update_metadata ovstorage update-metadata ADDRESS Same precondition model.
ovstorage_create_directory ovstorage create-directory ADDRESS Also CLI mkdir.
ovstorage_copy ovstorage cp SRC DEST Source/destination preconditions are explicit.
ovstorage_move ovstorage mv SRC DEST Also CLI rename.
ovstorage_delete ovstorage delete ADDRESS Also CLI rm.
ovstorage_delete_directory ovstorage delete-directory ADDRESS Recursive and dry-run are arguments.
ovstorage_connections_list ovstorage list-routes MCP exposes configured connections.
ovstorage_address_roots_list ovstorage list-routes MCP exposes visible address roots directly.

Unsupported gaps

MCP v0 does not expose diff, sync, list-versions, get-latest-version, check-access, watch-directory, or cache/state diagnostic commands such as cache-status, cache-doctor, and state-status. Use the CLI for those workflows.

See also