AgentSky
Log inSign up

Use AgentSky as an MCP server

Updated October 25, 2026

Point any MCP client at AgentSky to manage agents and sessions with tool calls.

AgentSky exposes its developer API as a Model Context Protocol (MCP) server. Claude Code, Codex, Cursor, and other MCP-compatible tools can use it to create agents, start sessions, send messages, search the catalog, and more — all as native tool calls.

MCP endpoint: POST https://api.agentsky.dev/v1/mcp

How to connect:

  1. Create an API key in Settings › API keys.
  2. Add the AgentSky MCP server to your MCP client configuration. Use the endpoint above and your API key as the bearer token.
  3. In Claude Code, for example, add to your MCP config: 
    {
  "mcpServers": {
    "agentsky": {
      "url": "https://api.agentsky.dev/v1/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}
  4. The tool list will load automatically. Use tools like list_agents, start_session, send_message, search_catalog, list_workspaces.

Everything else you can do in AgentSky: search_api finds the API operation for any action on agentsky.dev or in the Mac app (threads, Library files and skills, agents, workspaces, connectors, vaults, routines, billing, …), describe_api shows its parameters, and call_api runs it with your own key — the same checks and answer as calling the REST API.

Help Center tools: help_search and help_get are on this server, and also on a second, keyless server at https://api.agentsky.dev/v1/help/mcp that needs no API key. Every cloud session already has the keyless one, so you can just ask your agent how AgentSky works.

Where: API / any MCP client

Good to know: You can also install the agentsky skill locally with sky setup — this wires up the MCP server and catalog for your local agent in one step. Related: Use the AgentSky API, Create and manage API keys, Use the sky CLI.

Account and channel controls also have named tools. request_account_deletion queues the same irreversible deletion request as Settings; use it only on the person's explicit instruction, with confirm: "DELETE" and an unrestricted personal admin key. WhatsApp is a plugin: add_plugin with chat:whatsapp and the agent that answers it starts QR pairing and answers the pairing page as next.url; the person still scans the QR with WhatsApp. The tools the gateway offers, with their prices, are list_plugins with view: "discover"; reading them grants nothing.

To use the workspace's plugins in a local Codex, export_plugin answers one plugin as a Codex plugin package and export_plugin_marketplace answers every switched-on plugin as a Codex marketplace folder (no tokens are included). From a terminal, sky plugins marketplace --format codex --out <dir> writes that folder, and codex plugin marketplace add <dir> adds it.

For an authorized Mac host mount, mac_device_tools lists concrete device_* operations plus existing host tools and their exact argument schemas. mac_device_call calls one advertised operation using a stable request_id; reuse it on retry. Device administration must be separately allowed for device_* controls on the Mac. Account ownership, destination/path grants and macOS permissions remain enforced. Handle required_action rather than repeatedly attempting a blocked operation. CLI equivalents are sky mac tools and sky mac call; raw IPC names and arbitrary settings patches are refused.

Break reminders use device_list_reminders, device_create_reminder, device_update_reminder, device_delete_reminder, device_snooze_reminder, device_test_reminder and device_pause_reminders on that same host mount with device_configuration authority. They share the reminders visible in Settings › This Mac. Pass enabled: false to create one disabled without scheduling a notification; use device_update_reminder to enable it later. Pause affects every break reminder, so call it only when the person asks. Test sends a real sample notification. For one enabled reminder, device_snooze_reminder takes its exact id and reuses the notification's ten-minute Snooze without changing its repeating interval or other reminders. Hours, weekdays and Pause all still apply; missing or disabled ids are refused. The local agentsky-reminders MCP server exposes the same action as snooze_reminder. These controls do not manage the separate Apple Reminders app.

Mac automation settings have a separate owner interface: read_mac_automation, update_mac_automation and revoke_mac_automation require an unrestricted account-wide personal admin key, including for reads. A workspace/task key or ordinary host mount cannot authorize itself. Read the current revision and supported choices, change only intended grants with expected_revision, and reuse request_id on retry. Revoking disables automation and invalidates active permits, while retaining the configured choices. CLI: sky mac automation show|set|revoke. Approve exact sites with browser_origins (browserOrigins in CLI policy JSON), for example ["https://example.com", "http://localhost:3000"]. Origins include only the scheme, host and optional port; no path, wildcard or credentials. The empty default approves no sites. Explicit local/private origins are allowed. Site scope stays bound to the account, Mac and workspace and never grants local files; uploads also require the separately approved folder roots. Automated reaches do not inherit remembered manual Chrome sites.

Personal Arena uses its own authenticated tools, separate from anonymous community statistics: read state, boards or a match with read_personal_arena, read_personal_arena_boards and read_personal_arena_match. Starting a preset with start_personal_arena_preset requires billing normal and a stable retry identity; free starts remain retired. vote_personal_arena_match records one owned-match verdict and reveals identities through the normal billing owner. Public comments require explicit consent; read, post or remove your own comment with the corresponding personal Arena comment tools. CLI: sky personal-arena.

Mac host/device callers accept an optional transport workspace: a slug selects that workspace and null explicitly selects your default workspace. Omitting it uses the key-bound workspace or the Mac enrollment workspace. The server checks membership, key scope and any task binding; placing workspace in tool arguments does not grant access. CLI equivalents use --workspace <slug> or --personal-workspace. Ordinary device tool arguments remain separate. Office draft export creates a new file by default. Explicit replaceExisting requests replacement of a regular file inside an authorized writable folder; protected paths and symlinks are refused by the native owner. The relay envelope remains limited to 1 MiB. For larger Office or PNG files, upload through the existing Files API, then supply fileId, exact sizeBytes and lowercase sha256 instead of inline office or dataUrl. The native owner streams the same workspace file, checks its byte count and SHA-256, and commits only while destination authorization remains current. For large chart captures, provide filePath to save directly and receive a small byte-count/hash receipt. local_sync_now includes local service exports only when include_local_services: true and separate local_services_export authority are both present. A normal task folder grant or the argument alone cannot authorize reading environment files or exporting a local database.

Exact native owner administration uses dedicated named tools for app data access, custom blocked folders, screen reach, remembered app/site decisions, setup Files consent, native sign-in state/cancellation, available local providers, chart capture/export, global local-sync settings and lifecycle requests. These tools use the single /desktop/machines/{id}/administration/{exact_operation} path with the account owner's unrestricted personal admin key. Ordinary tasks and mount grants cannot authorize this channel; raw IPC and secret-key ingress are not exposed. CLI: sky mac administration, whose help lists the closed operations.

sign_out_mac, relaunch_mac and restart_mac_to_update return pending admission only; execution follows acknowledgement. Never describe that response as completed sign-out, restart or installation. Keep the same request_id on retries. list_legacy_mac_drafts returns bounded summaries, opaque ids and source version. adopt_legacy_mac_draft adopts only an explicitly selected draft into the current account's unsent drafts; it never sends it or automatically switches workspace.

Meeting notes use the existing context search: search_context with scope: "meetings/" or sky context search "Ada" --scope meetings/. The folder includes both historical meeting facts and current note artifacts. Participant names and identity sources, meeting start/end times, topics, observed screen shares and presented documents are searchable lines. Missing observations remain unknown; a document shown on screen is not evidence of an attachment sent. Historical facts are projected safely, excluding internal contexts, biometric vectors, local paths and URL credentials. Search and read use the same projection.

Sign a local Mac in without putting a key in tool arguments

A signed-out Mac can be signed in by an authorized agent running on that Mac. Pipe the existing credential loader into sky mac sign-in --key-stdin (or use an inherited pipe with --key-fd). This invokes the same native sign-in owner as the app and preserves its key, account and OS permission checks.

For local MCP, configure the stdio server sky mac auth-mcp. Its sign_in_mac tool accepts only a single-use secret_ref: the agent obtains it by piping the credential loader into sky mac prepare-sign-in --key-stdin. The reference expires in 30 seconds and cannot cross an authentication change. Never put the API key in a prompt, tool argument, shell argument, report or ordinary file. This same-user Unix socket is local bootstrap; hosted MCP cannot sign a signed-out remote Mac in. See the local Mac authentication architecture for its bounded Unix /v1/auth/* routes and profile socket option.

Vault secret values stay write-only. Environment-variable secret metadata includes allowed_hosts. In call_api PATCH /vaults/{id}/secrets/{secretId}, omit allowed_hosts to keep the current sites, send a list to replace them, or send [] to stop credential injection. In the CLI, use sky vault secret rotate <vaultId> <secretId> --keep-value --clear-hosts to clear sites without replacing the value; --host replaces them instead and cannot be combined with --clear-hosts.

For an authorized Mac browser reach, use mac_browser_download with the current read_page AX link ref and an authorized file_path. This saves the actual page download (including a generated Share Blob), without another Save click when the workspace, site and folder are already authorized. It returns a download_id; use mac_browser_download_status until completed, then verify output.size_bytes and output.sha256. mac_browser_downloads lists only that reach, and mac_browser_cancel_download cancels only its agent-owned items. If native commit has already been admitted, cancellation returns saving; poll mac_browser_download_status for the final receipt instead of assuming cancellation. Human downloads remain human-owned. These tools call the same POST /v1/desktop/mounts/{mount}/tools/{tool} owner as sky mac browser-download, browser-downloads, browser-download-status and browser-cancel-download. No arbitrary URL argument, extra local-file permission or Chrome permission is implied. Keep the original request_id when retrying one operation.

All four browser download REST callers require a personal write key, including list/status. Their read-only annotations describe behavior and do not waive the POST relay scope check. The GET tools directory remains available with read scope.

Local Claude Code and Codex use the same download, downloads, download_status and cancel_download tools through the turn's loopback MCP server. Local downloads use the already selected project folder and approved browser site, including signed-out subscription and Only on this Mac turns; no new platform login, enrollment or automation setting is required. A remotely started local turn retains its original host scope as an additional boundary. The start receipt can return before the background native stream finishes. Stopping the turn or revoking its original scope cancels its pending downloads.

capture_mac_arena_chart also exports a complete Mac comparison Result with arguments: {target: {kind: "thread-result", threadId: "THREAD_ID"}} and the checked workspace argument. It opens a normal Mac window and includes every Result row and column. Use filePath for large PNGs. target and the old rect mode are exclusive. A failed fact read or unrevealed blind Result refuses the export; running status and authorized unknown costs remain faithful snapshots. Navigation, changed facts or lost authorization invalidate the capture. After result_changed, retry with a new request_id. A workspace file never grants access to a thread. This Mac capability does not export the Web-local card.

View as Markdown