Skip to main content
Capabilities are what an agent can use beyond its harness’s built-in tools: MCP servers, and plugins from marketplaces, which bring skills, subagents, hooks, and MCP servers of their own. A template declares them, and each agent adds, overrides, or removes its own on top. Every entry point, a template document, the agent’s sub-resources, the console, and an agent’s export, takes and returns the same entries.

MCP servers

An MCP server is either remote, reached by URL, or local, run in the sandbox by a command.
Credentials a server needs, such as a token in headers, belong on the agent rather than in a template every agent shares. Add the server to the agent with its own token.

Marketplaces and plugins

The plugin is the only install unit. A marketplace is a public Git repository with a marketplace file (.claude-plugin/marketplace.json, which both harnesses read, or Codex’s .agents/plugins/marketplace.json). A plugin is a directory it lists, named plugin@marketplace.
  • source is host/owner/repo of a public repository, cloned from https://<source>.git at its default branch.
  • A plugin’s marketplace must be one of the agent’s effective marketplaces; adding a plugin without one, or deleting a marketplace a plugin still names, is 400.
  • The harness’s own CLI clones the marketplace and installs the plugin inside the sandbox, so paddock stores none of their content.

Skills, subagents, and hooks

Skills, subagents, and hooks are not configured on their own: they come inside plugins, as Agent Skills directories, subagent definitions, hooks, and MCP servers in the Agent Plugins layout or the harness’s own. A plugin is accepted whatever parts it has; a part the harness ignores, such as a plugin’s subagents on Codex, is reported as a warning. What each session’s harness actually loaded is in its harness status.

Change an agent’s capabilities

Each kind is a collection on the agent: mcp, marketplaces, plugins, and env. Every collection lists the agent’s effective entries, the template’s with the agent’s own applied, each with its source (template or agent) and the generation at which it last changed.
To pick up new commits of a marketplace, refresh it. Every session then updates the marketplace and reinstalls the plugins that come from it:
A marketplace is always its repository’s default branch. A session installs it at the commit the branch points to when the session installs it, and keeps that commit until the next refresh, so sessions that installed at different times may run different commits; each session’s config.applied events say which.

When a change takes effect

Changes to the model, MCP servers, marketplaces, and plugins reach sessions that are already running. Each such change raises the agent’s generation by one when it actually changes the agent’s configuration; setting a value to what it already is raises nothing. Every session’s harness is then brought to that generation between its turns, with the harness’s own commands, and without restarting the harness or ending its background work: A session that never runs again is never touched. Each application is recorded in the session’s history as one config.applied event: which entries were added, changed, removed, or refreshed, how (hot, or start before the process started), the plugin version or marketplace commit the harness reported, and any error or warning. A change that failed is recorded with its error and tried again only when its entry changes or is refreshed. A session’s observedGeneration is the generation its harness runs. While it is below the agent’s generation, the session has a change pending:
The system prompt, environment, permissions, and small model work differently: they are fixed when a session is created and reach only sessions created afterwards. See Configuration.

Harness support

An agent’s capabilities field reports the same for its harness. See Claude Code and Codex.