Skip to main content
An MCP Server component packages a service endpoint implementing the Model Context Protocol. By wrapping an MCP server in a volume, you make it discoverable and installable through any bibliotheca, with content integrity and provenance attached. Any MCP-compatible runtime — Claude Code, Cursor, Cline, and others — can then install and run your server through the standard Agent Volumes workflow.

​
Entrypoint format

MCP Server entrypoints must be JSON (.json) files. JSON is the only v0.1 baseline format for MCP server configuration in Agent Volumes — this is an interoperability convention that ensures consistent discovery across tools and runtimes. The canonical discovery filename is .mcp.json at the volume root. You should use this path unless you have a specific reason not to. The portable validation minimum requires:
  • The entrypoint file exists and is a regular file.
  • The file is valid JSON.
  • The file parses to a JSON object (not an array or primitive).
If your MCP server configuration is at a path other than .mcp.json, the runtime or validator will load it successfully but emit a noncanonical-entrypoint warning. Use .mcp.json to avoid this warning and ensure consistent discovery.

​
Declaring an MCP server in volume.toml

Add a [[components]] entry with type = "mcp-server" and point entrypoint to your .mcp.json configuration file.
A complete manifest for a volume that exports an MCP server:

​
Execution model

An MCP server runs as a long-running process separate from the agent runtime. The three supported transport mechanisms are: How the runtime launches the process, manages its lifecycle, and applies allow/deny policy are load-time decisions — they are not part of the portable validation that Agent Volumes performs on the component itself.

​
Protocol compatibility declaration

If your MCP server targets a specific protocol version, declare it in the [[protocols]] table. This is advisory metadata that runtimes and tooling can use to filter compatible servers.
Protocol version expressions are advisory metadata in Agent Volumes v0.1. A runtime that does not understand how to evaluate an MCP version expression must treat it as informational rather than applying it as a hard filter.

​
Runtime compatibility

To signal that your MCP server is compatible with specific runtimes, add a [[runtimes]] entry. The generic-mcp identifier covers any MCP-compatible client:

​
Validation requirements

An MCP server entrypoint fails portable validation if any of these conditions are true:
  • The file does not exist or is not a regular file.
  • The file is not valid JSON.
  • The parsed JSON is not an object (is an array, string, number, boolean, or null).
Runtime-specific failures — the server cannot be launched, local policy blocks it, an allow/deny list rejects it — are load-time failures. They do not make the manifest structurally invalid.
Combine your MCP server with related Tool or Skill components in the same volume. A consumer who installs the volume gets both the MCP server and the additional agent-facing components in a single install.

​
Component identifier

Once published, reference the MCP server component using a purl identifier:
For scoped volumes: