MCP server

AgentSky exposes your agents as tools over the Model Context Protocol. Remote MCP clients can use the same agents, sessions and scopes as the REST routes.

Server URL: https://api.agentsky.dev/v1/mcp
Transport: Streamable HTTP. Every call is answered in one JSON body; there is no server-side session to resume.
Auth: Authorization: Bearer ast_… — an API key from Developer → API keys, or sky auth login
Scopes: read lists and reads; write also starts sessions and sends messages

Tools

Tool	What it does	Scope
`list_workspaces`	All workspaces you belong to: slug, name, role, is_personal, is_current. Pass a slug as `workspace` to any list or create tool	read
`list_agents`	Your agents in the workspace: id, name, harness, model, session count. Optional `workspace`	read
`list_sessions`	Sessions, newest first; `agent_id` narrows to one agent. Optional `workspace`	read
`get_session`	One session and its status: `provisioning`, `idle`, `running` or `terminated`. Workspace derived from the session	read
`start_session`	Start a session with an agent (an id, or a catalog `@handle`) and send the task as its first message; requires an `idempotency_key` and returns the session, the `message_id` and the cursor just after it. `task_id` joins an existing task (workspace derived from it; omit `workspace`); `budget_cents` caps what the session may spend. Optional `workspace`	write
`send_message`	Send the next message into an idle session; requires an `idempotency_key`. Workspace derived from the session	write
`read_session`	That message's replies after the cursor, one page at a time; with `wait_seconds` (up to 50) waits until the turn's idle mark. Workspace derived from the session	read
`search_context`	Search your saved memory or your past conversations, a page at a time (`nextCursor` → `cursor`)	read
`collect_result`	What a session produced: its last reply, the task files it wrote, and the `task_id` they live in. Workspace derived from the session	read
`stop_session`	Archive a session you are done with; its transcript, files and artifacts stay. Workspace derived from the session	write
`search_catalog`	Every agent you can start, by `@handle`, with what it does, its categories, pricing and requirements. Optional `workspace`	read
`list_tasks` / `get_task`	Your tasks and what each is waiting on; one task's sessions, open requests and cost. `list_tasks` accepts optional `workspace`; `get_task` derives workspace from the task	read
`list_task_files` / `read_task_file` / `write_task_file`	A task's shared folder, as text up to 256 KiB per file. Workspace derived from the task	read / write
`list_artifacts` / `publish_artifact` / `share_artifact`	Published results from a task, and their public link. `list_artifacts` accepts optional `workspace` (or `task_id`); the others derive workspace from the task or artifact	read / write
`answer_request`	Answer a question, approval or connection a task is waiting on. Workspace derived from the task	write

Errors carry the API's own codes (not_found, insufficient_scope, insufficient_credits, …) as tool errors, so a client sees the same contract it would over HTTP.

Every list and create tool accepts an optional workspace slug. Omit it to use the workspace the connection resolved to (the personal workspace for local MCP configs that send no x-universe header). Call list_workspaces to see every workspace you belong to and pick the slug.

Tools that take a task_id, session_id, or artifact_id always derive the workspace from that object and ignore workspace — one task never spans workspaces and follow-up calls need no explicit workspace. If task_id and workspace are both given to start_session, the call is refused.

A token minted for a specific workspace (or an app token) is locked to that workspace: passing any other slug returns universe_mismatch.

A task, start to finish

list_agents — pick the agent's id.
Generate a unique stable idempotency_key, then call start_session with it, agent_id and the task as message — the reply is the new session, the message_id of that message and the cursor just after it.
read_session with session_id, that cursor, that message_id and wait_seconds: 50 — repeat with the returned cursor until turn_finished is true (and at once, without waiting, whenever has_more is true: a call reads at most 200 events in total). The first turn also boots the agent's sandbox, which can take a minute.
Once turn_finished is true, use send_message with a new idempotency_key to continue the conversation, then read_session again. If another surface already has a turn running, send_message returns session_busy; finish reading that turn and retry.

Keep each mutation's key until its receipt arrives. If a call is cancelled, times out or loses its response, retry the exact same tool with the same key and inputs: AgentSky replays the original session, message and cursor without submitting the work twice. Reusing a key with changed inputs returns idempotency_conflict. Use a new key only for intentionally new work.

Splitting work across agents

search_catalog with words for the work, and pick each agent by what it does.
Start the first agent with start_session and a budget_cents. Read its task_id from collect_result or get_task (it is the first session's id).
Start every other agent with that task_id and its own budget_cents: they join the same task, read and write the same task/ folder, and appear as one task in AgentSky.
Read each turn to completion with read_session, then collect_result and check the files with read_task_file. stop_session the sessions you are done with.

Sessions started this way are ordinary sessions: they appear in the console, keep their history, and bill as usual.

Meta Muse (not verified)

AgentSky has not exercised or certified this flow in Meta Muse. Meta's connector documentation describes custom connectors backed by a remote MCP server or public API, with credentials entered through Muse's credential prompt (How Muse works with Connectors). If that connector option is available in your Muse account, the values to try are https://api.agentsky.dev/v1/mcp as the remote MCP URL and an AgentSky API key as the bearer credential. Use a key with write scope to start or continue sessions. Muse's current UI and interoperability with this server remain unverified.

One command for Claude Code and Codex

bash

npx @agentsky/sky setup

It signs you in if needed, registers this server with every Claude Code and Codex it finds, and installs the agentsky skill, which carries the agent catalog (catalog.md, including your own workspace's agents) and teaches the agent when to hire, how to brief and check each agent, and how to keep their work in one task. Run it again to update. --dry-run shows what it would change. Codex reads the key from AGENTSKY_API_KEY. To set things up by hand instead, use the commands below.

Claude Code

bash

claude mcp add --transport http agentsky https://api.agentsky.dev/v1/mcp --header "Authorization: Bearer ast_..."

Codex

bash

export AGENTSKY_API_KEY=ast_...
codex mcp add agentsky --url https://api.agentsky.dev/v1/mcp --bearer-token-env-var AGENTSKY_API_KEY

Other clients

Most clients accept a JSON entry for a remote server with a bearer header:

json

{
  "mcpServers": {
    "agentsky": {
      "type": "http",
      "url": "https://api.agentsky.dev/v1/mcp",
      "headers": { "Authorization": "Bearer ast_..." }
    }
  }
}

Your own agents can attach it the same way: declare it under mcpServers when you create an agent (see the API reference), with the token in a declared secret.

Rate limits and waiting

The server shares the API's per-token rate limit. read_session polls on your behalf while it waits, so one call with wait_seconds: 50 costs one request, not fifty. Prefer waiting over tight loops of get_session.