> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Capabilities

> Give agents MCP servers, plugin marketplaces, plugins, and the skills inside them, and know when a change reaches a running session.

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.

```yaml theme={null}
spec:
  mcp:
    - name: github                       # remote
      url: https://api.githubcopilot.com/mcp/
      headers:
        Authorization: Bearer <token>
    - name: postgres                     # runs in the sandbox
      command: npx
      args: ["-y", "@modelcontextprotocol/server-postgres"]
      env:
        DATABASE_URL: postgres://...
```

| Field | Meaning |
| - | - |
| `name` | Letters, digits, `_`, `.`, `-`, starting with a letter or digit; up to 128 characters |
| `url`, `headers` | A remote server: an `https` URL and the headers to send |
| `command`, `args`, `env` | A local server: a program in the sandbox, such as `npx`, `uvx`, or an installed binary |

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`.

```yaml theme={null}
spec:
  marketplaces:
    - name: acme                          # the name the marketplace file declares
      source: github.com/acme/agent-plugins
  plugins:
    - name: release-tools@acme
    - name: experimental@acme
      enabled: false
```

* `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](https://agentskills.io) directories, subagent definitions, hooks, and MCP servers in the [Agent Plugins](https://agent-plugins.org) 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](https://docs.paddock.build/guides/harness-status.md).

## 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.

```go Go theme={null}
_, err := agent.MCP.Add(ctx, paddock.McpEntry{
	Name:    "linear",
	URL:     "https://mcp.linear.app/mcp",
	Headers: map[string]string{"Authorization": "Bearer " + os.Getenv("LINEAR_TOKEN")},
})
if err != nil {
	return err
}
_, err = agent.Marketplaces.Add(ctx, paddock.MarketplaceEntry{Name: "acme", Source: "github.com/acme/agent-plugins"})
if err != nil {
	return err
}
entry, err := agent.Plugins.Add(ctx, paddock.PluginEntry{Name: "release-tools@acme"})
if err != nil {
	return err
}
fmt.Println("generation", entry.Generation)

// Disable it, then remove it.
_, err = agent.Plugins.Update(ctx, "release-tools@acme", paddock.PluginEntry{Name: "release-tools@acme", Enabled: paddock.Ptr(false)})
if err != nil {
	return err
}
err = agent.Plugins.Delete(ctx, "release-tools@acme")
```

```python Python theme={null}
import os

agent.mcp.add(
    {
        "name": "linear",
        "url": "https://mcp.linear.app/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['LINEAR_TOKEN']}"},
    }
)
agent.marketplaces.add({"name": "acme", "source": "github.com/acme/agent-plugins"})
entry = agent.plugins.add({"name": "release-tools@acme"})
print("generation", entry.generation)

# Disable it, then remove it.
agent.plugins.update("release-tools@acme", {"name": "release-tools@acme", "enabled": False})
agent.plugins.delete("release-tools@acme")
```

```ts TypeScript theme={null}
await agent.mcp.add({
  name: "linear",
  url: "https://mcp.linear.app/mcp",
  headers: { Authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
});
await agent.marketplaces.add({ name: "acme", source: "github.com/acme/agent-plugins" });
const entry = await agent.plugins.add({ name: "release-tools@acme" });
console.log("generation", entry.generation);

// Disable it, then remove it.
await agent.plugins.update("release-tools@acme", { name: "release-tools@acme", enabled: false });
await agent.plugins.delete("release-tools@acme");
```

| Operation | Rule |
| - | - |
| `add(entry)` | `409 conflict` if the agent already added that name. On a name only the template has, it creates the agent's override |
| `update(name, entry)` | `404` if the name is not in the effective set. On a template entry, it creates the agent's override |
| `delete(name)` | Removes the agent's entry, which restores the template's entry of that name if there is one; `409` on an entry only the template has |
| `list()`, `get(name)` | The effective entries, ordered by name |
| Any operation on a kind the harness does not support | `422 unsupported` |

To pick up new commits of a marketplace, refresh it. Every session then updates the marketplace and reinstalls the plugins that come from it:

```go Go theme={null}
_, err := agent.Marketplaces.Refresh(ctx, "acme")
```

```python Python theme={null}
agent.marketplaces.refresh("acme")
```

```ts TypeScript theme={null}
await agent.marketplaces.refresh("acme");
```

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:

| The session | The change is applied |
| - | - |
| Has no harness process yet | When its next turn starts the process, before the process starts |
| Has a process and no running turn | At once |
| Has a turn running | When the turn ends; a running turn never sees a change |

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:

```go Go theme={null}
a, err := client.Agents.Get(ctx, agent.ID)
if err != nil {
	return err
}
s, err := client.Sessions.Get(ctx, session.ID)
if err != nil {
	return err
}
if s.ObservedGeneration < a.Generation {
	fmt.Println("the session has not taken the latest change yet")
}
```

```python Python theme={null}
a = client.agents.get(agent.id)
s = client.sessions.get(session.id)
if s.observed_generation < a.generation:
    print("the session has not taken the latest change yet")
```

```ts TypeScript theme={null}
const a = await paddock.agents.get(agent.id);
const s = await paddock.sessions.get(session.id);
if (s.observedGeneration < a.generation) console.log("the session has not taken the latest change yet");
```

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](https://docs.paddock.build/guides/configuration.md).

## Harness support

| Capability | Claude Code | Codex |
| - | - | - |
| MCP servers | Yes | Yes |
| Marketplaces and plugins | Yes | Yes; a plugin's subagents are ignored with a warning |
| Workflows | Yes, read-only through `agent.workflows` | No |
| Memory | Yes | Yes |

An agent's `capabilities` field reports the same for its harness. See [Claude Code](https://docs.paddock.build/harnesses/claude-code.md) and [Codex](https://docs.paddock.build/harnesses/codex.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.