> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aosplane.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aosplane.io/_mcp/server.

# MCP server

The AOSplane MCP server lets the AI tools you already use start sessions, follow them, send messages and answer permission requests. You add one URL to your client and sign in with your AOSplane account. There's no key to copy.

The server address is `https://mcp.aosplane.io/mcp`.

> **Note**
>
> The server acts as you, in the organization you sign in to, with your role. It can't do anything you couldn't do in the dashboard.

## Add it to your client

#### Claude Code

Run this, then type `/mcp` in Claude Code to sign in:

```bash
claude mcp add --transport http aosplane https://mcp.aosplane.io/mcp
```

#### Cursor

Add this to `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "aosplane": { "url": "https://mcp.aosplane.io/mcp" } } }
```

#### VS Code

Add this to `.vscode/mcp.json`:

```json
{ "servers": { "aosplane": { "type": "http", "url": "https://mcp.aosplane.io/mcp" } } }
```

#### Codex

Add this to `~/.codex/config.toml`, then run `codex mcp login aosplane`:

```toml
[mcp_servers.aosplane]
url = "https://mcp.aosplane.io/mcp"
```

#### Claude Desktop

In Claude or Claude Desktop, add a custom connector and paste `https://mcp.aosplane.io/mcp` as its URL.

Any other client that supports remote MCP servers over HTTP with OAuth sign-in works the same way.

## Sign in

#### Check the request

Your client opens a browser page called **Connect** followed by the client's name and **to AOSplane?** It lists what the client will be able to do and where you'll be sent back.

#### Continue

Choose **Continue to sign in**. Choose **Cancel** if you didn't start this from an app you trust.

#### Sign in with AOSplane

Sign in as you do on the web. If you belong to more than one organization, pick the one the client should work in under **Choose an organization**.

#### Go back to your client

The browser returns you to the client, which can now use the AOSplane tools.

Try asking your client: "List my AOSplane projects, then start a session in acme/web that fixes the failing test."

## What your client can do

| Group         | Tools                                                                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sessions**  | List projects, agents, repositories and sessions, get one session, start a session, fork it, send a message, switch its agent, pause, resume, cancel and archive it. |
| **Follow**    | Wait for a session to finish its turn or need you, read its conversation, read its changes, list tasks it delegated, and get a link to a QA check video.             |
| **Approvals** | List and answer an agent's permission requests, and list or revoke saved approvals.                                                                                  |
| **Preview**   | Share a port the sandbox serves as a private preview link, list previews and stop sharing them.                                                                      |

#### Every tool by name

* **Read only:** `list_projects`, `list_agents`, `list_repositories`, `list_runs`, `get_run`, `wait_for_run`, `get_transcript`, `get_run_diff`, `list_child_runs`, `get_qa_recording`, `list_permission_requests`, `list_permission_grants`, `list_ports`.
* **Change something:** `start_run`, `fork_run`, `send_message`, `switch_agent`, `pause_run`, `resume_run`, `archive_run`, `answer_permission_request`, `revoke_permission_grant`, `expose_port`, `unexpose_port`.
* **Can't be undone:** `cancel_run` stops a session for good, along with any tasks it delegated.

## Good to know

* Sessions started from your client show up in the dashboard like any other, so you can open them there too.
* Your client answers a permission request once. It can't save an "always allow". Questions from the agent and plan approvals are answered in the dashboard.
* To give a client fewer tools, add `?read_only=true` to the URL to leave out every tool that changes something, or `?toolsets=sessions,follow` to pick groups (`sessions`, `follow`, `approvals`, `preview`). This keeps the list short, but it isn't a security boundary.
* Each person can make 120 requests a minute and have 4 waits open at once. A wait lasts up to 5 minutes, then your client simply waits again.
* If you sign out of AOSplane or are removed from the organization, the client stops working until you sign in again.

## Related

* [Start a session](/start-a-session)
* [Chat and approve requests](/session-chat)
* [API keys](/api-keys)
* [Desktop app](/desktop-app)