Docs · Agents

Use froog as an MCP server

froog is one MCP server for all of your agent's infrastructure. Claude Code, Codex, Cursor, Claude Desktop and any other MCP client get every froog product as tools: Quicksand sandboxes (create, run, fork, snapshot, files), Tokenmail inboxes (wait for a code, read and search mail), Pushbox CI (why a run failed), and the account itself (usage, billing, API keys, organizations, webhooks). Everything you can do in the dashboard, the CLI or the API is a tool, 258 in all. The 42 core ones are listed by default and the rest by toolset. Every call obeys your API key's scope. There are two ways to connect, with the same tools:

  • Local: froog mcp runs the server on stdio, signed in like the CLI (froog login, or FROOG_API_KEY in its environment).
  • Hosted: https://api.froogcorp.com/mcp (Streamable HTTP) with an API key in the header Authorization: Bearer froog_…, or, for clients that sign in through the browser (Claude's custom connectors, ChatGPT), OAuth: see Connect with a sign-in. Nothing to install.

Claude Code

$ claude mcp add froog -- froog mcp
# or hosted:
$ claude mcp add --transport http froog https://api.froogcorp.com/mcp --header "Authorization: Bearer $FROOG_API_KEY"

Add --scope user to have it in every project.

Codex

$ codex mcp add froog -- froog mcp

Hosted, in ~/.codex/config.toml (the key is read from FROOG_API_KEY):

[mcp_servers.froog]
url = "https://api.froogcorp.com/mcp"
bearer_token_env_var = "FROOG_API_KEY"

Cursor: in ~/.cursor/mcp.json (or .cursor/mcp.json in a project), one of:

{ "mcpServers": { "froog": { "command": "froog", "args": ["mcp"] } } }

{ "mcpServers": { "froog": {
    "url": "https://api.froogcorp.com/mcp",
    "headers": { "Authorization": "Bearer ${env:FROOG_API_KEY}" } } } }

Claude Desktop: Settings, Developer, Edit Config, then in claude_desktop_config.json (Claude Desktop doesn't see your shell's PATH, so give the full path that which froog prints):

{ "mcpServers": { "froog": {
    "command": "/Users/you/.local/bin/froog",
    "args": ["mcp"],
    "env": { "FROOG_API_KEY": "froog_…" } } } }

Any other client: run froog mcp as a stdio server, or point it at https://api.froogcorp.com/mcp with the Authorization header.

Connect with a sign-in (OAuth)

Claude (claude.ai and Claude Desktop: Settings, Connectors, Add custom connector), ChatGPT and other clients that can't send a header connect to https://api.froogcorp.com/mcp with just the URL. froog follows the MCP authorization spec (OAuth 2.1 with PKCE):

  1. The client gets 401 with WWW-Authenticate: Bearer resource_metadata="https://api.froogcorp.com/.well-known/oauth-protected-resource/mcp", reads that and /.well-known/oauth-authorization-server, and registers itself (POST /oauth/register, dynamic client registration, public clients only, redirect URIs over https, to localhost, or an app's own scheme).
  2. Your browser opens froog's sign-in (Google, as on the dashboard), then a page that names the client and where it sends you back, and asks what it may do: ci (the default: create sandboxes, run commands, stop and start them, delete the ones it created), full-sandbox (use existing sandboxes only) or read-only.
  3. On Allow, the client gets an access token: a new API key with that preset, labeled mcp: CLIENT NAME, that expires in 30 days. It's in froog api-key list and the dashboard like any key. Revoke it there (or the client calls POST /oauth/revoke). Its creation is in the audit log. There are no refresh tokens: after 30 days the client asks you to sign in again.

To get every toolset in a connector, add it as https://api.froogcorp.com/mcp?toolsets=all (or names like ?toolsets=billing,orgs): the sign-in is the same.

A malformed authorization request (a bad response_type, no PKCE, another resource) shows an error page. froog sends the browser back to the client's redirect URI only after you answer the consent page (with access_denied on Deny). API keys keep working as bearer tokens on the same URL. Self-hosted control planes turn OAuth on with FROOG_SERVER_MCP_OAUTH=on (it needs Google sign-in set up). While it's off, the OAuth URLs answer 404.

ToolDoes
list_sandboxesSandboxes with state, size, OS and labels. Filter by label, state, name_prefix.
create_sandboxA new sandbox (name, size, os, from a saved snapshot, env, labels, ttl_secs, setup). Waits until it runs.
sandbox_infoOne sandbox in full.
execRun a bash command (command, cwd, env, timeout_secs up to 3600). Returns the exit code, stdout and stderr.
start_sandbox, stop_sandboxStart (waits until it runs) or stop (keeps the disk).
delete_sandboxDelete for good. Needs confirm: true.
fork_sandboxCopy a sandbox, or one of its snapshots, into new_name. Waits until the copy runs.
save_snapshot, list_snapshotsSave a snapshot (with a label, a template for create_sandbox from). List a sandbox's snapshots, or the account's saved ones.
read_file, write_file, list_dirFiles in a running sandbox: text as is, binary as base64.
host_portAn HTTPS URL for a port (private with a token unless public).
desktop_linkA 10-minute link to watch and use the desktop.
prompt_agentRun a coding agent inside the sandbox on a prompt (agent, model, effort) and return its answer.
start_jobStart a bash command in the background (command, cwd, env), like froog exec --detach. Returns the job id at once.
list_jobs, job_logs, kill_jobA sandbox's background commands. One job's state, exit code and output from offset (pass the returned next_offset to read only what's new). Stop one.
list_inboxes, create_inboxTokenmail inboxes: list them, or make one (username, domain, name, client_id, sandbox, a paid seat).
wait_for_emailWait for the next email in an inbox (sender, subject, up to 120 s) and return it with its one-time codes and verification links pulled out.
list_messages, get_message, search_messagesRead mail: filter by labels, sender, subject and direction. One message with its text, reply text, headers and attachments. Full-text search.
list_threads, get_threadConversations, and one with all its messages.
send_email, reply_to_email, forward_emailSend, reply (or reply_all) in the thread, forward with attachments. Each is sent once even if the call is retried. Not on yet: they answer mail_send_off.
update_labelsAdd and remove labels (remove unread to mark it read).
create_draft, send_draftA draft (new, a reply or a forward, send_at schedules it), and sending it.
list_mail_eventsWhat happened in your inboxes since a cursor. wait_secs Holds the call until something does.
list_ci_runs, get_ci_runPushbox workflow runs, newest first, with each job's state and id (filter by repo, state such as failed, workflow, branch, words). One run by GitHub's run id. Read-only, like all the CI tools.
get_ci_job, ci_job_logs, ci_job_testsOne CI job: why it failed, its wait and run time. The end of its log as text (tail_lines, default 400). Its failed tests from JUnit XML.
search_ci_logs, ci_analyticsSearch finished jobs' logs line by line (branch:main level:error timeout). Failure rates, p50/p90 times, cost, size advice and flaky tests per repository and job.

The rest of the API: toolsets

The tools above are the core set, listed to every client. Everything else you can do in the dashboard, the CLI or the API is a tool too (216 more), grouped in toolsets that a client lists when it asks for them. That keeps the default list short for clients that cap how many tools they load.

# hosted: add ?toolsets= to the URL (all, or names separated by commas)
$ claude mcp add --transport http froog "https://api.froogcorp.com/mcp?toolsets=all" --header "Authorization: Bearer $FROOG_API_KEY"
# local
$ claude mcp add froog -- froog mcp --toolsets billing,orgs   # or FROOG_MCP_TOOLSETS=all
ToolsetTools
sandboxesThe rest of each sandbox: file search and edits, ports and URLs, metrics and processes, command history, agent prompts, snapshots and shares.
59 tools: close_port, create_download_url, create_upload_url, create_url_token, delete_auto_snapshots, delete_conversation, delete_file, delete_saved_snapshot, delete_snapshot, download_from_saved_snapshot, download_from_snapshot, find_in_files, get_browser_link, get_command, get_conversation, get_prompt, get_sandbox_metrics, get_sandbox_metrics_history, get_sandbox_usage, get_saved_snapshot, get_snapshot, get_ssh_info, get_stop, interrupt, list_account_snapshots, list_commands, list_conversations, list_ports, list_process_records, list_process_samples, list_processes, list_prompts, list_snapshot_shares, list_url_tokens, list_urls, make_directory, move_file, open_port, queue_prompt, read_command_logs, remove_url, replace_in_files, restore_sandbox, revoke_snapshot_share, revoke_url_token, sandbox_provider_models, saved_snapshot_file_info, search_files, set_file_permissions, set_ports, share_sandbox, share_saved_snapshot, snapshot_file_info, steer, touch_sandbox, unshare_sandbox, update_sandbox, wait_for_port, write_job_stdin
mailThe rest of Tokenmail: inbox settings, drafts, domains, forwarding, allow and block lists, suppressions, attachments, metrics.
51 tools: add_inbox_list_entry, add_mail_list_entry, batch_get_inbox_messages, batch_update_inbox_messages, buy_inboxes, confirm_forwarding_verification, create_mail_domain, delete_inbox, delete_inbox_draft, delete_inbox_forwarding, delete_inbox_message, delete_inbox_thread, delete_mail_domain, delete_mail_forwarding, get_any_inbox_thread, get_inbox, get_inbox_attachment, get_inbox_billing, get_inbox_draft, get_inbox_draft_attachment, get_inbox_forwarding, get_inbox_list_entry, get_inbox_message_raw, get_inbox_metrics, get_mail_domain, get_mail_domain_setup_link, get_mail_domain_zone_file, get_mail_forwarding, get_mail_list_entry, get_mail_metrics, list_all_inbox_drafts, list_all_inbox_messages, list_all_inbox_threads, list_inbox_drafts, list_inbox_list_entries, list_mail_domains, list_mail_list_entries, list_mail_suppressions, remove_inbox_list_entry, remove_mail_list_entry, remove_mail_suppression, search_inboxes, send_inbox_welcome, set_inbox_forwarding, set_mail_forwarding, start_forwarding_verification, update_inbox, update_inbox_draft, update_inbox_thread, update_mail_domain, verify_mail_domain
ciCI settings, monitors and job metrics.
6 tools: create_ci_monitor, delete_ci_monitor, get_ci_job_metrics, get_ci_overview, list_ci_monitors, set_ci_settings
accountThe account, usage, limits, alerts, data retention, the audit log.
17 tools: close_account, create_dashboard_link, export_audit, get_account, get_alert_settings, get_data_retention, get_deletion_operation, get_limits, get_status, get_usage, list_audit_events, list_connections, list_images, reopen_account, send_feedback, update_alert_settings, update_data_retention
billingWallet, card, auto top-up, spending cap.
8 tools: add_card, billing_portal, get_billing, set_auto_topup, set_extra_starts, set_spend_cap, wallet_pay, wallet_quote
keysAPI keys and SSH keys.
7 tools: add_ssh_key, create_api_key, list_api_keys, list_ssh_keys, remove_ssh_key, revoke_api_key, rotate_api_key
orgsOrganizations, members, invitations, seats.
15 tools: create_org, delete_org, get_org, invite_org_member, leave_org, list_org_members, list_orgs, preview_org_invite, remove_org_member, revoke_org_invite, set_active_org, set_org_seats, transfer_org, update_org, update_org_member
environmentsThe account environment, named environments, environment variables.
16 tools: create_environment, delete_environment, get_environment, get_named_environment, list_env, list_environment_versions, list_environments, remove_env, remove_environment_file, remove_named_environment_file, set_env, set_environment_file, set_named_environment_file, update_environment, update_named_environment, upgrade_environment
githubThe GitHub connection and its repositories.
5 tools: connect_github, disconnect_github_installation, get_github, list_github_repos, set_github_token_repos
webhooksWebhooks and the OpenTelemetry endpoint.
11 tools: add_webhook, get_telemetry, get_webhook, list_webhook_deliveries, list_webhooks, remove_telemetry, remove_webhook, rotate_webhook, set_telemetry, test_webhook, update_webhook
aiAI credentials and profiles, the AI proxy, Claude and ChatGPT subscriptions.
21 tools: add_ai_credential, cancel_subscription_login, create_ai_profile, delete_ai_profile, get_ai_profile, get_ai_proxy, get_ai_usage, get_sandbox_ai, get_subscription_login, list_ai_profiles, list_subscriptions, provider_models, remove_ai_credential, send_subscription_code, set_ai_environment_profile, sign_out_subscription, start_subscription_login, switch_ai_credential, update_ai_profile, update_ai_proxy, update_sandbox_ai
  • Each tool is one API route and runs exactly as that route does over HTTP: the same arguments (path, query and JSON body fields side by side), the same answer, and the same key scope. A read-only key can't change billing, and only a full-access key can make API keys. Its name is the route's operation id in openapi.json, in snake case.
  • Any tool can be called by name, listed or not.
  • Tools that can't be undone, or that spend money (every delete, plus wallet_pay, close_account, rotate_api_key, transfer_org, leave_org, restore_sandbox, set_org_seats and rotate_webhook) refuse to run without confirm: true, and are marked destructiveHint so the client asks you first.
  • Left out on purpose: joining an organization is a person's choice: they open the invitation link (acceptOrgInvite). Signs a terminal in: a person approves it in the browser (approveCliLogin, denyCliLogin, getCliLogin, pollCliLogin, startCliLogin). A signed URL is for a plain HTTP client. Create_download_url returns one (downloadSigned). A GitHub token for the sandbox's own git helper, not one to put in a chat (getSandboxGithubToken). For people without an account (joinWaitlist). A live stream. The list and get tools poll the same data (listEvents, mailEventsSocket, promptEvents, watchFiles, watchPorts). An HTML page for a person's browser. Get_mail_domain_setup_link returns its link (mailDomainSetupPage). The MCP endpoint itself (mcp). Sign-in methods decide who can get into the account: changed only in the dashboard (removeConnection, sendConnectionEmailCode, setPrimaryConnection, verifyConnectionEmailCode). A binary upload. Create_upload_url returns a URL to PUT the tarball to (uploadArchive). A signed URL is for a plain HTTP client. Create_upload_url returns one (uploadSigned).
  • create_sandbox, fork_sandbox and start_sandbox wait up to 120 seconds (wait: false returns at once). exec and read_file return at most 256 KiB of output (the end of a long output, the start of a long file).
  • A failed call is a tool error whose text is the API's error, {"error":{"code":…,"message":…,"request_id":…}}, so the agent sees why (not_found, api_key_action_forbidden, an empty wallet) and you can quote the request id.
  • Give the agent a scoped key. The tools obey the key's scope exactly like the HTTP routes they stand for: with froog api-key create agent --preset ci, an agent can create sandboxes and delete only the ones it created. With --preset read-only, it can only look.
  • Output as it runs. An exec call that sends _meta.progressToken gets its output as notifications/progress while the command runs (progress: the bytes so far, message: the new output), then the usual result. froog mcp writes them on stdout. The hosted endpoint answers that call as server-sent events when the client accepts text/event-stream.
  • The hosted endpoint is stateless: each POST gets one JSON answer (or, for a call with a progress token, one event stream that ends with the answer), with no session id (GET answers 405). It speaks MCP 2025-06-18, 2025-03-26 and 2024-11-05. Tool calls count toward the same per-IP request limit as the API.