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

# Manage Resources

> Add and remove MCP servers and skills at runtime

A workspace's resources are not fixed at creation time. MCP servers and skills can be added or removed while the workspace is running, and every change is persisted so it survives restarts. The lifecycle methods round out the picture, taking a workspace from provisioned to released.

## Manage MCP Servers

`add_mcp` registers a new MCP server and `remove_mcp` deregisters one by name. Changes are written to the `.mcp` file under the workspace directory, so a restarted workspace reconnects the same servers without re-seeding:

```python theme={null}
from agentscope.mcp import MCPClient, HttpMCPConfig

# Register a new MCP server; raises ValueError if the name already exists
await workspace.add_mcp(
    MCPClient(
        name="amap",
        is_stateful=False,
        mcp_config=HttpMCPConfig(url="https://mcp.amap.com/mcp?key=..."),
    ),
)

# Deregister by name; unknown names log a warning and return silently
await workspace.remove_mcp("amap")

# Enumerate the currently registered clients
mcps = await workspace.list_mcps()
```

<Note>
  Persistence follows the workspace's own model: an ephemeral `DockerWorkspace` without a host `workdir` keeps the MCP list in memory only, and it is lost when the container goes away.
</Note>

## Manage Skills

`add_skill` copies a local skill directory (which must contain a `SKILL.md`) into the workspace's `skills/` directory, packaging it as a tar archive so the copy works the same against a local directory or a remote sandbox. `remove_skill` deletes a skill by its agent-facing name (the `name` field in the `SKILL.md` front matter):

```python theme={null}
# Copy a local skill directory into the workspace;
# raises ValueError if SKILL.md is missing or the directory already exists
await workspace.add_skill("./skills/web-search")

# Delete by the skill's front-matter name; raises KeyError if not found
await workspace.remove_skill("web-search")

# Enumerate the available skills (parsed from each SKILL.md)
skills = await workspace.list_skills()
```

## Manage the Lifecycle

Three methods take a workspace through its life, and the `async with` protocol wraps `initialize` / `close` for scoped use:

| Method         | Effect                                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `initialize()` | Provision the backend (start the container / sandbox / Pod), connect MCP servers, and seed skills                |
| `reset()`      | Return the workspace to an empty state: close and remove all MCPs, delete all skills, and wipe per-session state |
| `close()`      | Release all resources and connections                                                                            |

```python theme={null}
async with LocalWorkspace(workdir="./ws") as workspace:
    ...  # initialize() on entry, close() on exit
```

<Warning>
  `reset()` empties the workspace; it does not restore the initial state. The constructor-time `default_mcps` and `skill_paths` seeds are **not** re-applied.
</Warning>

## Allocate Workspaces in a Service

In a multi-tenant service, deciding which request gets which workspace (per user, per agent, or per session), caching live instances, and evicting idle ones is the job of the **workspace manager**, a separate service-side component. See its dedicated chapter:

<Card title="Workspace Manager" icon="server" href="/versions/2.0.5dev/en/deploy/workspace-manager" cta="View deployment docs" arrow>
  Allocation, isolation policies, TTL eviction, and integration with the Agent Service.
</Card>