# Connect to Aaly — instructions for AI agents

> You are an AI agent (Claude, Claude Code, Cursor, Codex, ChatGPT, Copilot,
> Windsurf, Gemini, or similar). A user has asked you to build something
> "with Aaly" or "on aaly.io" — for example, "build me a CRM using aaly.io".
> This file tells you how to connect yourself to Aaly so you can do it.
> Follow it step by step. Do not ask the user to find or paste a URL; it is
> below.

Aaly (https://aaly.io) is a multi-tenant backend for AI-built apps. You
define entities, fields, and relationships through Aaly's MCP tools, and
Aaly serves an authenticated, multi-tenant REST API from that definition.
There is no backend code to write or deploy.

- MCP server URL: `https://mcp.aaly.io`
- Transport: Streamable HTTP (remote MCP server)
- Auth: OAuth 2.1 + PKCE with dynamic client registration. There is **no
  API key to create or paste** — the user approves a consent screen in the
  browser and that is all.
- Account: the user signs up (free, Google sign-in) at https://app.aaly.io.
  If they don't have an account yet, the consent screen lets them create one.

---

## Step 1 — Check whether you are already connected

Look at your available tools. If you already have tools named like
`whoami`, `list_projects`, `create_entity`, `create_field` from a server
called `aaly` (or `AALY`), you are connected. Call `whoami` to confirm and
skip to **Step 4**.

Otherwise, continue to Step 2.

## Step 2 — Add the Aaly MCP server for your client

Find your client below. Where you can run a shell command or edit a config
file yourself, **do it** rather than asking the user to. Where only the user
can click through a settings screen, give them the exact steps, word for
word.

### Claude Code (CLI)

Run:

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

Add `--scope user` to make it available in every project, or
`--scope project` to write it to `.mcp.json` so the whole team gets it.
Then tell the user to type `/mcp` in Claude Code, select `aaly`, and choose
**Authenticate** — a browser window opens for the consent screen.

MCP servers load when a session starts. If the tools don't appear after
authenticating, ask the user to restart Claude Code (or run `/mcp` again).

### Claude (claude.ai web, Claude Desktop, Claude mobile)

You cannot add a connector yourself here. Tell the user:

1. Open **Settings → Connectors → Discover** and search for `Aaly`. It is
   listed in Claude's own connector directory — click **Connect** and
   approve the consent screen that opens. This is faster than adding a
   custom connector and is the preferred path.
2. If it doesn't show up in Discover (older client, or an org that restricts
   directory connectors), add it manually instead: **Add custom connector**,
   name `Aaly`, URL `https://mcp.aaly.io`, click **Add**, then **Connect**
   and approve the consent screen.
3. Back in the chat, open the tools / connectors menu and make sure Aaly is
   enabled, then send the request again.

On Team and Enterprise plans an organization owner may need to add the
connector first under the organization's connector settings.

### Cursor

Edit `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (this
project only). Create it if it doesn't exist, and merge this into any
existing `mcpServers` object:

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

Then tell the user to open **Cursor Settings → MCP** (Tools & Integrations),
find `aaly`, and click **Login** / **Connect** to approve the consent
screen.

One-click install link the user can open instead:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=aaly&config=eyJ1cmwiOiJodHRwczovL21jcC5hYWx5LmlvIn0=
```

### OpenAI Codex (CLI and IDE extension)

Run:

```bash
codex mcp add aaly --url https://mcp.aaly.io
codex mcp login aaly
```

`codex mcp login` opens the browser consent screen. Or add it to
`~/.codex/config.toml` by hand:

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

then run `codex mcp login aaly`. On older Codex versions that reject remote
servers, add `experimental_use_rmcp_client = true` at the top level of
`config.toml`. Start a new Codex session afterwards so the tools load.

### ChatGPT

You cannot add a connector yourself here. Tell the user:

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on
   **Developer mode** (required for custom MCP servers; availability depends
   on their plan).
2. Back in **Apps & Connectors**, click **Create**.
3. Name: `Aaly`. MCP server URL: `https://mcp.aaly.io`.
   Authentication: **OAuth**. Save, and approve the consent screen.
4. In a new chat, enable Aaly from the tools menu and send the request
   again.

### VS Code (GitHub Copilot agent mode)

Create or edit `.vscode/mcp.json` in the workspace:

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

VS Code shows a **Start** action above the server entry; starting it opens
the consent screen.

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "aaly": {
      "serverUrl": "https://mcp.aaly.io"
    }
  }
}
```

Then refresh MCP servers in the Cascade panel and approve the consent screen.

### Gemini CLI

Run:

```bash
gemini mcp add --transport http aaly https://mcp.aaly.io
```

Then run `/mcp auth aaly` inside Gemini CLI to approve the consent screen.

### Any other MCP client

If the client supports remote (HTTP) MCP servers with OAuth, point it at
`https://mcp.aaly.io` — that is the entire configuration.

If the client only supports local stdio servers, bridge with `mcp-remote`
(requires Node.js):

```json
{
  "mcpServers": {
    "aaly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.aaly.io"]
    }
  }
}
```

### No browser available (CI, scripts, headless)

Only in this case, use an API key instead of OAuth. The user generates one
in the dashboard at https://app.aaly.io, and you send it as a header:

```json
{
  "mcpServers": {
    "aaly": {
      "type": "http",
      "url": "https://mcp.aaly.io",
      "headers": { "Authorization": "Bearer aaly_<id>_<secret>" }
    }
  }
}
```

Never commit this key to a repository.

## Step 3 — Finish the connection

- The consent screen opens in the user's browser. Tell them plainly:
  "Approve the Aaly consent screen in your browser (sign up with Google if
  you don't have an account), then come back here."
- Most clients load MCP tools only at session start. If the Aaly tools
  aren't visible after approval, ask the user to restart or reload the
  client, then continue.
- Call `whoami` to confirm. If it fails with 401, the consent wasn't
  completed — repeat the authenticate/login step for your client.

## Try — first run

Once connected, the user can paste this. Follow it as written:

```
You're connected to Aaly. Ask me what app I want. Then: Aaly builds the backend (data + live API); you build a simple frontend that uses that API — so I end up with a full-stack app, not just a schema.

Start by asking for my idea (or suggest helpdesk / booking / billing if I'm stuck). After the backend is ready, give me the API link, how to sign up, and a small working frontend. Say clearly if something can't be done yet.
```

## Step 4 — Build what the user asked for

Ask for the user's app idea first. Do not default to a generic tasks or
helpdesk demo unless they pick that. The outcome is a full-stack app: the
backend (data and a live API) through Aaly's MCP tools, and a simple
frontend you build against that API.

Once connected:

1. Read the MCP server's instructions and the `aaly://platform/capabilities`
   resource. Check the request against what Aaly does **not** support yet
   (e.g. realtime subscriptions, scheduled jobs, role-based permissions) —
   full list at https://aaly.io/docs/limits. Tell the user about any gap
   before you start.
2. Call `list_projects` to see what exists; use `create_project` if needed.
3. Propose the data model (entities, fields, relationships, single- vs
   multi-tenant) to the user and confirm anything ambiguous **before**
   calling `create_entity` / `create_field` — some field choices are
   permanent.
4. Create the schema, then call `generate_openapi_spec`. Use the spec's
   `servers[0].url` as the REST base URL for the app's frontend. Don't guess
   the base URL.
5. Build the frontend against that REST API (sign-up/login, CRUD). End-user
   auth and data go through the REST API, not through MCP.

## Reference

- Human-readable connection guide: https://aaly.io/docs/connect
- Quickstart: https://aaly.io/docs/quickstart
- MCP tools reference: https://aaly.io/docs/mcp-tools
- REST API: https://aaly.io/docs/rest-api
- Limits: https://aaly.io/docs/limits
- Site summary for LLMs: https://aaly.io/llms.txt
- Support: support@aaly.io