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 mcpruns the server on stdio, signed in like the CLI (froog login, orFROOG_API_KEYin its environment). - Hosted:
https://api.froogcorp.com/mcp(Streamable HTTP) with an API key in the headerAuthorization: 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):
- The client gets
401withWWW-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, tolocalhost, or an app's own scheme). - 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) orread-only. - 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 infroog api-key listand the dashboard like any key. Revoke it there (or the client callsPOST /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.
| Tool | Does |
|---|---|
list_sandboxes | Sandboxes with state, size, OS and labels. Filter by label, state, name_prefix. |
create_sandbox | A new sandbox (name, size, os, from a saved snapshot, env, labels, ttl_secs, setup). Waits until it runs. |
sandbox_info | One sandbox in full. |
exec | Run a bash command (command, cwd, env, timeout_secs up to 3600). Returns the exit code, stdout and stderr. |
start_sandbox, stop_sandbox | Start (waits until it runs) or stop (keeps the disk). |
delete_sandbox | Delete for good. Needs confirm: true. |
fork_sandbox | Copy a sandbox, or one of its snapshots, into new_name. Waits until the copy runs. |
save_snapshot, list_snapshots | Save 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_dir | Files in a running sandbox: text as is, binary as base64. |
host_port | An HTTPS URL for a port (private with a token unless public). |
desktop_link | A 10-minute link to watch and use the desktop. |
prompt_agent | Run a coding agent inside the sandbox on a prompt (agent, model, effort) and return its answer. |
start_job | Start a bash command in the background (command, cwd, env), like froog exec --detach. Returns the job id at once. |
list_jobs, job_logs, kill_job | A 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_inbox | Tokenmail inboxes: list them, or make one (username, domain, name, client_id, sandbox, a paid seat). |
wait_for_email | Wait 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_messages | Read mail: filter by labels, sender, subject and direction. One message with its text, reply text, headers and attachments. Full-text search. |
list_threads, get_thread | Conversations, and one with all its messages. |
send_email, reply_to_email, forward_email | Send, 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_labels | Add and remove labels (remove unread to mark it read). |
create_draft, send_draft | A draft (new, a reply or a forward, send_at schedules it), and sending it. |
list_mail_events | What happened in your inboxes since a cursor. wait_secs Holds the call until something does. |
list_ci_runs, get_ci_run | Pushbox 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_tests | One 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_analytics | Search 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
| Toolset | Tools |
|---|---|
sandboxes | The 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 |
mail | The 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 |
ci | CI 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 |
account | The 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 |
billing | Wallet, 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 |
keys | API 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 |
orgs | Organizations, 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 |
environments | The 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 |
github | The GitHub connection and its repositories. 5 tools: connect_github, disconnect_github_installation, get_github, list_github_repos, set_github_token_repos |
webhooks | Webhooks 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 |
ai | AI 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-onlykey 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_seatsandrotate_webhook) refuse to run withoutconfirm: true, and are markeddestructiveHintso 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_sandboxandstart_sandboxwait up to 120 seconds (wait: falsereturns at once).execandread_filereturn 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
execcall that sends_meta.progressTokengets its output asnotifications/progresswhile the command runs (progress: the bytes so far,message: the new output), then the usual result.froog mcpwrites them on stdout. The hosted endpoint answers that call as server-sent events when the client acceptstext/event-stream. - The hosted endpoint is stateless: each
POSTgets one JSON answer (or, for a call with a progress token, one event stream that ends with the answer), with no session id (GETanswers 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.