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

# MCP

> Expose a small sandbox management surface without flattening every provider tool into one server.

Archal provides a management-plane MCP server for sandbox lifecycle and state.
Provider operations remain on each environment's own REST or MCP connection.

## Local stdio

Run the lifecycle server for an MCP client that supports stdio:

```bash theme={null}
archal mcp
```

The CLI reads its protected Archal credential. Do not pass that credential to
the agent under test.

## Hosted Streamable HTTP

Connect to:

```text theme={null}
https://archal.ai/api/mcp
```

Authenticate the management connection with the Archal workspace bearer key.
Provider MCP connections use the returned environment `mcpUrl` and exact
`credentials.headers` map instead.

## Lifecycle tools

* `environments_list`
* `environment_describe`
* `sessions_list`
* `session_create`
* `session_status`
* `session_wait`
* `state_validate`
* `state_get`
* `state_load`
* `state_diff`
* `session_reset`
* `session_renew`
* `session_destroy`
* `evidence_get`

Hosted `session_create` can return while provisioning continues. Use
`session_wait` or poll `session_status` before giving connections to a test.
Hosted destroy can acknowledge durable teardown before physical deletion.

## Keep the tool boundary small

The lifecycle MCP server does not federate thousands of GitHub, Slack, Jira,
and other provider tools into one namespace. When an environment returns an
`mcpUrl`, connect to that provider surface separately with its short-lived
credential. This keeps lifecycle authority distinct from the agent's task tools.

State loading and reset are destructive. A trusted coding agent may propose
them, but it should not execute them without approval for the exact target or a
preconfigured disposable CI boundary.