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_agents`	Your agents: id, name, harness, model, session count	read
`list_sessions`	Sessions, newest first; `agent_id` narrows to one agent	read
`get_session`	One session and its status: `provisioning`, `idle`, `running` or `terminated`	read
`start_session`	Start a session with an agent 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	write
`send_message`	Send the next message into an idle session; requires an `idempotency_key` and returns the session, the `message_id` and the cursor just after it. A running session returns `session_busy`	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. Errors the turn records are listed; a retrying error does not end the turn	read
`search_context`	Search your saved memory or your past conversations, a page at a time (`nextCursor` → `cursor`)	read

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.

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.

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.

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.

MCP server

Tools#

A task, start to finish#

Meta Muse (not verified)#

Claude Code#

Codex#

Other clients#