Reference
MCP reference
Connect to Zeish and discover every organization and admin tool.
On this page
Use the MCP server
Connect an MCP client to Zeish over Streamable HTTP.
Endpoint: https://api.zei.sh/api/v1/mcp. Send Authorization: Bearer with a zeish_live_ API key or an OAuth access token.
The server exposes organization tools for sandboxes, templates, volumes, networks, secrets, SSH keys, and identity. Superadmins also receive platform operations.
There are no direct MCP tools for raw TCP tunnel access, port sharing, or secret grants and leases. Use the public API or SDK for those operations.
1{"mcpServers":{"zeish":{"url":"https://api.zei.sh/api/v1/mcp","headers":{"Authorization":"Bearer zeish_live_..."}}}}Authenticate an MCP client
Choose an API key for headless use or OAuth for interactive clients.
Headless clients can send a standalone API key directly. Interactive connectors use OAuth Authorization Code with PKCE and dynamic client registration.
OAuth metadata is at /api/v1/.well-known/oauth-authorization-server. Register at /api/v1/mcp-auth/register, authorize at /api/v1/mcp-auth/authorize, and exchange codes at /api/v1/mcp-auth/token.
1Authorization: Bearer zeish_live_...Discover live tool schemas
Use tools/list instead of hard-coding an outdated tool catalog.
Call tools/list after connecting. The response is the source of truth for names, descriptions, and JSON schemas exposed by the deployed server.
Tool results are returned as text content. Validate arguments against the schema returned by the server.
1{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}Create a sandbox
Create a MicroVM in the caller's organization.
Tool: sandboxes_create
Input: {"name":"agent-run","templateId":"TEMPLATE_ID","cpu":4,"memory":4096}
Permission: MACHINE_CREATE.
Optional storage, network, ingress, labels, and secretInjection fields match the public create schema.
Response: The created sandbox record.
1{"name":"sandboxes_create","arguments":{"name":"agent-run","templateId":"TEMPLATE_ID","cpu":4,"memory":4096}}List sandboxes
List compact sandboxes in the caller's organization.
Tool: sandboxes_list
Input: {"limit":20,"cursor":"..."}
Permission: MACHINE_READ.
Use the returned nextCursor to continue pagination.
1{"name":"sandboxes_list","arguments":{"limit":20,"cursor":"..."}}Get sandbox details
Fetch one sandbox with access URL enrichment.
Tool: sandboxes_get
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_READ.
Inspect status and runtime metadata before data-plane work.
1{"name":"sandboxes_get","arguments":{"sandboxId":"SANDBOX_ID"}}Mint sandbox data-plane access
Mint credentials for commands and files.
Tool: sandboxes_exec_access
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
The token is sandbox-scoped and short-lived. Never log it.
Response: sandboxUrl, sandboxRpcUrl, token, and expiresAt.
1{"name":"sandboxes_exec_access","arguments":{"sandboxId":"SANDBOX_ID"}}Get a terminal URL
Create a browser terminal URL.
Tool: sandboxes_terminal_url
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_READ.
Open the returned URL in a browser.
1{"name":"sandboxes_terminal_url","arguments":{"sandboxId":"SANDBOX_ID"}}Sync SSH keys
Apply current user keys to an existing runtime.
Tool: sandboxes_sync_ssh_keys
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
Run after adding or removing an SSH key.
1{"name":"sandboxes_sync_ssh_keys","arguments":{"sandboxId":"SANDBOX_ID"}}Create a preview code
Create temporary HTTP access to a sandbox port.
Tool: sandboxes_create_preview_code
Input: {"sandboxId":"SANDBOX_ID","port":3000,"ttl_seconds":300}
Permission: MACHINE_READ.
Use base_url and the code for agents, and the handoff URL for browsers.
1{"name":"sandboxes_create_preview_code","arguments":{"sandboxId":"SANDBOX_ID","port":3000,"ttl_seconds":300}}List sandbox logs
Read bounded sandbox output.
Tool: sandboxes_list_logs
Input: {"sandboxId":"SANDBOX_ID","limit":"100","source":"app"}
Permission: MACHINE_READ.
Filter by service or source when diagnosing a run.
1{"name":"sandboxes_list_logs","arguments":{"sandboxId":"SANDBOX_ID","limit":"100","source":"app"}}List sandbox events
Read sandbox lifecycle events.
Tool: sandboxes_list_events
Input: {"sandboxId":"SANDBOX_ID","limit":"100"}
Permission: MACHINE_READ.
Use events to poll asynchronous transitions.
1{"name":"sandboxes_list_events","arguments":{"sandboxId":"SANDBOX_ID","limit":"100"}}Start a sandbox
Request a sandbox runtime to start.
Tool: sandboxes_start
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
Poll sandboxes_get until the status is running.
1{"name":"sandboxes_start","arguments":{"sandboxId":"SANDBOX_ID"}}Pause a sandbox
Pause a sandbox while retaining its state.
Tool: sandboxes_pause
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
Resume the sandbox before requesting fresh data-plane work.
1{"name":"sandboxes_pause","arguments":{"sandboxId":"SANDBOX_ID"}}Resume a sandbox
Resume a paused sandbox.
Tool: sandboxes_resume
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
Wait for running before using commands or files.
1{"name":"sandboxes_resume","arguments":{"sandboxId":"SANDBOX_ID"}}Stop a sandbox
Stop a runtime and retain its record.
Tool: sandboxes_stop
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
Stop releases the active runtime without deleting the sandbox.
1{"name":"sandboxes_stop","arguments":{"sandboxId":"SANDBOX_ID"}}Kill a sandbox
Force-stop a stuck runtime.
Tool: sandboxes_kill
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_UPDATE.
Use this when a normal stop does not converge.
1{"name":"sandboxes_kill","arguments":{"sandboxId":"SANDBOX_ID"}}Delete a sandbox
Permanently delete a sandbox.
Tool: sandboxes_delete
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_DELETE.
Deletion is irreversible.
1{"name":"sandboxes_delete","arguments":{"sandboxId":"SANDBOX_ID"}}Create a snapshot
Capture a sandbox runtime state.
Tool: sandboxes_create_snapshot
Input: {"sandboxId":"SANDBOX_ID","displayName":"dependencies-v4"}
Permission: MACHINE_UPDATE.
Create from a live runtime and wait until ready.
1{"name":"sandboxes_create_snapshot","arguments":{"sandboxId":"SANDBOX_ID","displayName":"dependencies-v4"}}List snapshots
List snapshots owned by one sandbox.
Tool: sandboxes_list_snapshots
Input: {"sandboxId":"SANDBOX_ID"}
Permission: MACHINE_READ.
Snapshot IDs are scoped to their sandbox.
1{"name":"sandboxes_list_snapshots","arguments":{"sandboxId":"SANDBOX_ID"}}Delete a snapshot
Delete one sandbox snapshot.
Tool: sandboxes_delete_snapshot
Input: {"sandboxId":"SANDBOX_ID","snapshotId":"SNAPSHOT_ID"}
Permission: MACHINE_UPDATE.
Snapshot deletion is irreversible.
1{"name":"sandboxes_delete_snapshot","arguments":{"sandboxId":"SANDBOX_ID","snapshotId":"SNAPSHOT_ID"}}List templates
List templates visible to the organization.
Tool: templates_list
Input: {"limit":20,"cursor":"..."}
Permission: MACHINE_READ.
Use this to find a template ID for sandbox creation.
1{"name":"templates_list","arguments":{"limit":20,"cursor":"..."}}Get a template
Fetch one template by ID.
Tool: templates_get
Input: {"templateId":"TEMPLATE_ID"}
Permission: MACHINE_READ.
The response includes image and default runtime settings.
1{"name":"templates_get","arguments":{"templateId":"TEMPLATE_ID"}}Create a volume
Create persistent organization storage.
Tool: volumes_create
Input: {"name":"agent-data","region":"bremen","sizeGb":20}
Permission: ORG_MANAGE.
Attach the resulting volume ID to a sandbox.
1{"name":"volumes_create","arguments":{"name":"agent-data","region":"bremen","sizeGb":20}}List volumes
List organization volumes.
Tool: volumes_list
Input: {"limit":20,"cursor":"..."}
Permission: ORG_MANAGE.
Use nextCursor for additional pages.
1{"name":"volumes_list","arguments":{"limit":20,"cursor":"..."}}Get a volume
Fetch one volume by ID.
Tool: volumes_get
Input: {"volumeId":"VOLUME_ID"}
Permission: ORG_MANAGE.
Use the volume ID in sandbox configuration.
1{"name":"volumes_get","arguments":{"volumeId":"VOLUME_ID"}}Delete a volume
Delete one organization volume.
Tool: volumes_delete
Input: {"volumeId":"VOLUME_ID"}
Permission: ORG_MANAGE.
Remove dependencies before deleting storage.
1{"name":"volumes_delete","arguments":{"volumeId":"VOLUME_ID"}}Create a network
Create an organization network.
Tool: networks_create
Input: {"name":"agent-network","region":"bremen"}
Permission: ORG_MANAGE.
Attach the resulting network ID to a sandbox.
1{"name":"networks_create","arguments":{"name":"agent-network","region":"bremen"}}List networks
List organization networks.
Tool: networks_list
Input: {"limit":20,"cursor":"..."}
Permission: ORG_MANAGE.
Use nextCursor for additional pages.
1{"name":"networks_list","arguments":{"limit":20,"cursor":"..."}}Get a network
Fetch one network by ID.
Tool: networks_get
Input: {"networkId":"NETWORK_ID"}
Permission: ORG_MANAGE.
Use the network ID in sandbox configuration.
1{"name":"networks_get","arguments":{"networkId":"NETWORK_ID"}}Delete a network
Delete one organization network.
Tool: networks_delete
Input: {"networkId":"NETWORK_ID"}
Permission: ORG_MANAGE.
Detach dependent sandboxes before deleting it.
1{"name":"networks_delete","arguments":{"networkId":"NETWORK_ID"}}List secret metadata
List secrets without values.
Tool: secrets_list
Input: {}
Permission: ORG_MANAGE.
Use this to discover secret IDs. Values are never included.
1{"name":"secrets_list","arguments":{}}Get a secret
Read one audited secret value.
Tool: secrets_get
Input: {"secretId":"SECRET_ID"}
Permission: ORG_MANAGE.
Treat the result as sensitive and do not log it.
1{"name":"secrets_get","arguments":{"secretId":"SECRET_ID"}}Create a secret
Create a plaintext or JSON secret.
Tool: secrets_create
Input: {"name":"github-token","provider":"vault","providerReference":"secret/data/ci/github","value":"replace-me"}
Permission: ORG_MANAGE.
The configured deployment provider must be available.
1{"name":"secrets_create","arguments":{"name":"github-token","provider":"vault","providerReference":"secret/data/ci/github","value":"replace-me"}}Update a secret
Edit secret metadata or material.
Tool: secrets_update
Input: {"secretId":"SECRET_ID","name":"github-token-v2"}
Permission: ORG_MANAGE.
Send only the fields that should change.
1{"name":"secrets_update","arguments":{"secretId":"SECRET_ID","name":"github-token-v2"}}Delete a secret
Delete a secret.
Tool: secrets_delete
Input: {"secretId":"SECRET_ID"}
Permission: ORG_MANAGE.
Deletion is audited and removes provider material.
1{"name":"secrets_delete","arguments":{"secretId":"SECRET_ID"}}Get the caller identity
Read the authenticated profile and memberships.
Tool: users_whoami
Input: {}
Permission: Authenticated.
Use this to confirm the current user and organization context.
1{"name":"users_whoami","arguments":{}}List SSH keys
List keys authorized for sandbox provisioning.
Tool: ssh_keys_list
Input: {}
Permission: Authenticated.
Only public key material is returned.
1{"name":"ssh_keys_list","arguments":{}}Register an SSH key
Register a public SSH key.
Tool: ssh_keys_create
Input: {"name":"workstation","publicKey":"ssh-ed25519 AAAA..."}
Permission: Authenticated.
Sync the key into an existing sandbox separately.
1{"name":"ssh_keys_create","arguments":{"name":"workstation","publicKey":"ssh-ed25519 AAAA..."}}Delete an SSH key
Revoke a public SSH key.
Tool: ssh_keys_delete
Input: {"keyId":"KEY_ID"}
Permission: Authenticated.
The key no longer applies to future provisioning.
1{"name":"ssh_keys_delete","arguments":{"keyId":"KEY_ID"}}Use superadmin tools
Inspect platform users, billing, organizations, and nodes.
The admin tool family is available only to superadmins. tools/list exposes the exact schemas when the authenticated identity has access.
Available tools: admin_list_users, admin_get_user_detail, admin_list_user_sandboxes, admin_get_user_usage, admin_list_sandboxes, admin_get_sandbox_billing, admin_get_sandbox_events, admin_get_billing_overview, admin_get_billing_periods, admin_suspend_user, admin_reinstate_user, admin_list_organizations, admin_get_organization_billing, admin_grant_organization_credit, and admin_list_node_machines.
1{"name":"admin_list_users","arguments":{"page":1,"pageSize":20}}