# Use AgentSky as an MCP server > Point any MCP client at AgentSky to manage agents and sessions with tool calls. canonical: https://agentsky.dev/help/mcp-server source: https://agentsky.dev/help/mcp-server.md updated: 2026-10-25 --- **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: ```json { "mcpServers": { "agentsky": { "url": "https://api.agentsky.dev/v1/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 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](https://agentsky.dev/help/api-overview), [Create and manage API keys](https://agentsky.dev/help/api-keys), [Use the sky CLI](https://agentsky.dev/help/sky-cli-overview). 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 ` writes that folder, and `codex plugin marketplace add ` 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 ` 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 --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.