Sandbox Studio MCP Server

A local Model Context Protocol (MCP) server that connects AI assistants to the Sandbox Studio API. This lets you manage AWS sandbox accounts, leases, templates, events, and settings through natural language conversations.

Install

After installing, run npx sandbox-studio-mcp init to configure your credentials.

What is this?

Sandbox Studio is a platform for managing temporary AWS accounts — useful for training, labs, hackathons, and development sandboxes. This MCP server exposes the full Sandbox Studio API as tools that AI assistants (Claude, Kiro, Cursor, etc.) can call on your behalf.

Example conversations:

"Create a template for my students with a $50 budget and EC2 access only"

"Request a lease for the VS Code Server template and tell me when it's ready"

"Show me all pending approvals and deny Emma's requests"

"Terminate all my leases except the GPU one"

How it works

┌─────────────────┐      stdio       ┌──────────────────┐      HTTPS      ┌─────────────────────┐
│   AI Assistant  │◄────────────────►│   MCP Server     │◄───────────────►│   Sandbox Studio    │
│ (Kiro/Claude/   │                  │   (this project) │     OAuth2      │   API               │
│  Cursor)        │                  │                  │                 │                     │
└─────────────────┘                  └──────────────────┘                 └─────────────────────┘

1. The AI assistant spawns the MCP server as a local subprocess
2. When you ask a question, the AI decides which tools to call
3. The MCP server authenticates with Sandbox Studio using OAuth2 client credentials
4. API responses are returned to the AI, which formats them for you

Prerequisites

• Node.js >= 18
• pnpm (or npm)
• A Sandbox Studio instance with API access
• OAuth client credentials — create these in the Sandbox Studio admin panel

Quick Start

1. Configure credentials

npx sandbox-studio-mcp init

This will prompt you for:

• Instance URL — your Sandbox Studio API endpoint (e.g. https://sandbox.example.com/api)
• Client ID — from your OAuth client in the Sandbox Studio admin panel
• Client Secret — from your OAuth client

To create OAuth credentials, go to your Sandbox Studio admin panel → API Clients → Create new client.

2. Connect to your AI assistant

Kiro

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "sandbox-studio": {
      "command": "npx",
      "args": ["-y", "sandbox-studio-mcp"]
    }
  }
}

Claude Code

claude mcp add sandbox-studio -- npx -y sandbox-studio-mcp

Cursor / VS Code (manual)

Add to your MCP settings (or use the one-click badges above):

{
  "mcp": {
    "servers": {
      "sandbox-studio": {
        "command": "npx",
        "args": ["-y", "sandbox-studio-mcp"]
      }
    }
  }
}

Codex

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "sandbox-studio": {
      "command": "npx",
      "args": ["-y", "sandbox-studio-mcp"]
    }
  }
}

AI Behaviour Guidance

The MCP server includes guidance in tool descriptions that shapes how the AI interacts with you. This is one of the key design patterns of this project:

Safety guardrails

• Lease termination — When terminating multiple leases, the AI will list them clearly, distinguish between your own and others' leases, and ask for confirmation before proceeding.
• Bulk operations — The AI won't batch-terminate or batch-deny without explicit confirmation.

Template creation prompts

When creating templates, the AI is guided to ask about:

• Tags for categorisation
• Custom icon and colour
• Manager/approver configuration

Launch script convention

When the AI writes launch scripts for templates, it uses set-sandbox-output instead of echo to expose variables to the lease owner in the Sandbox Studio UI:

set-sandbox-output --name "Public IP" --value "$PUBLIC_IP"
set-sandbox-output --name "Admin Password" --value "$PASSWORD" --is-secret

The --is-secret flag masks the value in the UI.

Response enrichment

When templates or leases are created, the response includes a _link field with a direct URL to the resource in the Sandbox Studio UI.

OAuth2 Authentication

The server uses the OAuth2 client credentials grant flow:

1. On first API call, it requests a token from {instanceUrl}/oauth/token
2. The token is cached in memory with a 60-second refresh buffer
3. On 401 responses, it automatically clears the cache and retries
4. HTML responses (login page redirects) are detected and trigger a token refresh

To create OAuth credentials, go to your Sandbox Studio admin panel → API Clients → Create new client.

Available Tools (65+)

Leases

Tool	Description
list_leases	List leases with filtering by status, user, date
get_lease	Get lease details by ID
request_lease	Request a new lease from a template
update_lease	Update lease budget/duration/expiration
suspend_lease	Suspend an active lease
resume_lease	Resume a suspended lease
review_lease	Approve or deny a lease request
terminate_lease	Terminate a lease (irreversible)
withdraw_lease	Withdraw a pending request
get_lease_team_members	List shared users
share_lease	Share with additional users
unshare_lease	Remove shared users
get_lease_logs	Get setup/activity logs
get_lease_secrets	Get build output secrets

Templates

Tool	Description
list_public_templates	List templates available for lease requests
list_managed_templates	List templates you manage
create_template	Create a new template
get_template	Get full template details
delete_template	Delete a template
get_template_info	Get basic info (name, description, icon)
update_template_info	Update basic info
get_template_leases	List leases for a template
get_template_permissions	Get IAM permission config
update_template_permissions	Update IAM permissions
get_template_launch_settings	Get launch/setup scripts
update_template_launch_settings	Update launch/setup scripts
update_template_budget	Update budget settings
update_template_duration	Update duration settings
update_template_managers	Update managers/approvers
update_template_sharing	Update sharing settings
update_template_tags	Update tags

Accounts

Tool	Description
list_accounts	List sandbox accounts
list_unregistered_accounts	List available unregistered accounts
get_account	Get account details
import_accounts	Import AWS accounts into the pool
eject_accounts	Eject accounts from the pool
get_account_lease_history	Get lease history for an account
retry_account_cleanup	Retry failed cleanup
get_account_cleanup_logs	Get cleanup logs
get_account_failed_resources	Get failed cleanup resources

Events

Tool	Description
list_events	List events with status filtering
create_event	Create a new event
get_event	Get event details
update_event	Update an event
get_event_teams	Get event teams
add_event_teams	Add teams to an event
assign_event_team_owner	Assign a team owner
provision_event	Provision event accounts
start_event	Start a provisioned event
terminate_event	Terminate an event

Approvals & Reporting

Tool	Description
list_approvals	List pending approval requests
get_lease_costs	Get cost reporting data

Admin Jobs

Tool	Description
trigger_drift_detection	Run drift detection
trigger_lease_monitoring	Run lease monitoring

Settings

Tool	Description
get_global_config	Get global platform config
update_global_config	Update global config
get_runtime_config	Get runtime config
get_cleanup_settings	Get nuke config
update_cleanup_settings	Update nuke config
get_cleanup_hook	Get cleanup hook script
update_cleanup_hook	Update cleanup hook
get_email_settings	Get email templates
update_email_settings	Update email templates
send_test_email	Send test email
get_smtp_settings	Get SMTP config
update_smtp_settings	Update SMTP config

Users & Identity

Tool	Description
list_users	List users from identity provider
list_groups	List groups from identity provider
validate_users	Validate user IDs exist
update_preferences	Update user preferences
list_all_oauth_clients	List all OAuth clients (admin)
list_my_oauth_clients	List your OAuth clients
create_oauth_client	Create an OAuth client
update_oauth_client	Update an OAuth client
delete_oauth_client	Delete an OAuth client
get_terms_of_service	Get current terms of service
list_terms_versions	List ToS versions
get_terms_version	Get specific ToS version
publish_terms_of_service	Publish new ToS
get_tags	Get all template tags
validate_s3_path	Validate an S3 path

Project Structure

src/
├── index.ts          # Entry point — registers all tools, connects via stdio
├── config.ts         # Config file management (~/.sandbox-studio-mcp/config.json)
├── auth.ts           # OAuth2 client_credentials token management
├── client.ts         # HTTP client with auth, retry, and HTML detection
├── init-config.ts    # Interactive config setup CLI
└── tools/
    ├── leases.ts     # Lease lifecycle tools
    ├── accounts.ts   # Account pool management
    ├── templates.ts  # Template configuration (with AI guidance)
    ├── events.ts     # Events, approvals, reporting, admin jobs
    ├── settings.ts   # Cleanup, email, SMTP, global config
    └── users.ts      # Users, groups, OAuth clients, ToS, tags

Development

# Build
pnpm build

# Watch mode (rebuild on change)
pnpm dev

# Run directly
node dist/index.js

Extending

Adding a new tool

1. Choose the appropriate file in src/tools/
2. Register the tool with server.registerTool(name, schema, handler)
3. Use apiRequest(config, options) to call the Sandbox Studio API

Adding AI guidance

Use the tool's description field to influence AI behaviour:

server.registerTool("my_tool", {
  description: `Do something.

IMPORTANT: Always ask the user about X before calling this tool.
Never do Y without explicit confirmation.`,
  inputSchema: { ... }
}, handler);

This is the primary mechanism for shaping how AI assistants use your tools.

Troubleshooting

Problem	Solution
HTML responses instead of JSON	Check that instanceUrl in config includes /api
401 errors	Verify client credentials are valid and the OAuth client is active
Token refresh loops	The OAuth client may have been deleted — recreate in admin panel
Tools not appearing	Rebuild (pnpm build) and restart the MCP server

License

MIT