# Panes

Canonical: https://usepanes.com/docs/mcp

## Connect an agent

### Hosted agent MCP

Connect to **https://api.usepanes.com/mcp/agent** using Streamable HTTP. Discovery and signup work without a key. After `signup_verify`, store the key and reconnect with `Authorization: Bearer <key>` in your MCP client's secret headers. Every account tool checks that key. Browser cookies do not grant access.

The server advertises its complete tool schemas. JSON request data goes under `body`; path/query parameters are top-level. Use `request_key` for an idempotency header, `payment_authorization` for MPP and `payment_signature` for x402. Results include `http_status` and `body`, including the REST error's recovery action. Binary file reads return `body.content_base64`; screenshots are MCP images. The file limit is 1 MiB; use HTTP for larger files.

Example tool calls, in order:

```json
{"name":"catalog","arguments":{}}
{"name":"signup","arguments":{"body":{"email":"agent@example.com","key_name":"Office agent"}}}
{"name":"signup_verify","arguments":{"body":{"challenge_id":"<signup.challenge_id>","code":"<inbox code>"}}}
```

Reconnect with the issued key, then:

```json
{"name":"topup_quote","arguments":{"body":{"amount_cents":1000,"method":"usdc_x402"},"request_key":"office-credit-unique-01"}}
{"name":"topup_pay","arguments":{"id":"<topup.id>","payment_signature":"<authorized wallet proof>"}}
{"name":"topup_status","arguments":{"id":"<topup.id>"}}
{"name":"machine_create","arguments":{"body":{"template":"windows-16gb","name":"office-report","prevent_cloning":true,"require_office_ready":true,"auto_stop_minutes":15},"request_key":"office-computer-unique-01"}}
{"name":"exec","arguments":{"id":"<machine.id>","body":{"script":"Get-Date -Format o","desktop":true,"timeout_s":30}}}
{"name":"machine_stop","arguments":{"id":"<machine.id>"}}
```

Check live readiness and enabled payment rails before continuing. Follow the [quickstart](/docs#quickstart) for the real Office task, downloads and cost check. A wallet must already have funds and delegated authority. Do not pay again after uncertainty.

[Panes discovery JSON](https://api.usepanes.com/.well-known/panes.json) links the endpoint, docs and OpenAPI. It is supplemental Panes metadata. MCP clients use the transport and schemas above; no proprietary manifest support is required.

### Local MCP

The local MCP bridge exposes computer lifecycle, commands, files, screenshots, accessibility, mouse and keyboard tools. It uses the same Panes API key and prepaid balance as HTTP. Python 3.11 or later is required for MCP.

```bash
python3 -m venv .venv
.venv/bin/python -m pip install 'panes[mcp] @ https://usepanes.com/sdk/panes-0.1.5-py3-none-any.whl'
```

Set `PANES_API_KEY` in the agent client's secret environment. Configure the absolute path to the installed executable:

```json
{"mcpServers":{"panes":{"command":"/ABSOLUTE/PATH/.venv/bin/panes-mcp","args":[]}}}
```

On Windows use `C:\\PATH\\.venv\\Scripts\\panes-mcp.exe`. Do not paste keys into task prompts or source code.

Start by calling `account` and `templates`. Save a unique `request_key` before `machine_create`. For Office require a ready template, keep `prevent_cloning` true and use `desktop: true` for commands. Check exit codes and timeouts. Finish with `machine_stop`.

`machine_request` recovers a lost create reply. File tools carry base64 and cap payloads at 1 MiB; use direct HTTP or the SDK for larger files. The accessibility tool returns the native Windows UI Automation tree so agents can identify controls before clicking.

The [desktop MCP bundle](https://github.com/logancsack/panes-office-workflows/tree/main/integrations/desktop) and [finance workflow](https://github.com/logancsack/panes-office-workflows) are examples built on the same bridge.

### Signup and prepay through MCP

For a new agent, configure the same executable directory with `panes-onboard-mcp` instead of `panes-mcp`. It starts without a key and includes all computer tools plus this onboarding catalog:

| Tool | Arguments | Next step |
| --- | --- | --- |
| `catalog` | None | Check prices, payment methods and `office_ready` before paying. |
| `signup` | `email`, optional `key_name` | Read the email code through your own inbox API. |
| `signup_verify` | `challenge_id`, `code` | Store the returned key privately. This connection uses it immediately. |
| `payment_methods` | None | Choose an enabled rail. |
| `topup_quote` | `amount_cents`, `method`, `request_key` | Have an authorized wallet approve this exact quote. |
| `topup_pay` | `id`, `payment_authorization` for MPP or `payment_signature` for x402 | Read status; never send card numbers. |
| `topup_status` | `id` | Wait for `paid` before creating a computer. |

Use the [funding requests](/docs#funding) to obtain the wallet proof. The MCP server does not own a wallet or create spending authority. After a restart, set `PANES_API_KEY` to the stored key. After a lost verification reply, request another email code. After a lost payment reply, call `topup_status` for the original quote.

### OpenAI OAuth connector

The separate OpenAI OAuth connector is live; directory approval is pending. See [Panes for OpenAI agents](/openai) for its connection details. Connect an autonomous agent through the hosted agent endpoint or local MCP bridge above.

The connector links an existing Panes account through OAuth. You choose computers and permissions, set runtime limits and approve exact actions on Panes before they run. It does not provide signup, funding, checkout or automatic top-ups. The autonomous endpoint above and `panes-onboard-mcp` use the separate API-key catalog.