---
title: "Connect your AI agent to while over MCP"
url: https://while.sh/en/docs/get-started/connect-your-agent/
updated: 2026-11-09
---

# Connect your agent

Your agent connects itself when you give it the sentence. Otherwise, one command connects all your agents at once, and a connector connects your conversation.

## The simplest way: the sentence

Paste these instructions into your agent. It reads the page made for it and connects to while with your account: you authorize it in your browser. Then it deploys your app.

```text titre="Instructions"
Connect to while with my account (while.sh/agents), then deploy my app.
```

## All your agents in one command

In a terminal, this command connects while to Claude Code, Codex, Cursor, Gemini CLI and VS Code, if they are installed. It only changes their configuration files, in your home folder, without sudo. Run again, it duplicates nothing.

```sh titre="Terminal"
curl -fsSL https://app.while.sh/install.sh | sh
```

To see what it would do without writing anything, add `-s -- --dry-run` at the end.

## In a terminal

Or connect a single agent to the address of while's MCP server, `https://app.while.sh/mcp`:

```sh onglet="Claude Code" titre="Terminal"
claude mcp add --transport http --scope user while https://app.while.sh/mcp
```

```sh onglet="Codex" titre="Terminal"
codex mcp add while --url https://app.while.sh/mcp
codex mcp login while
```

```json onglet="Cursor" titre="~/.cursor/mcp.json"
{
  "mcpServers": {
    "while": { "url": "https://app.while.sh/mcp" }
  }
}
```

```json onglet="VS Code" titre=".vscode/mcp.json"
{
  "servers": {
    "while": { "type": "http", "url": "https://app.while.sh/mcp" }
  }
}
```

```sh onglet="Gemini CLI" titre="Terminal"
gemini mcp add --scope user --transport http while https://app.while.sh/mcp
```

In Cursor, [install while in one click](cursor://anysphere.cursor-deeplink/mcp/install?name=while&config=eyJ1cmwiOiJodHRwczovL2FwcC53aGlsZS5zaC9tY3AifQ==). In VS Code too: [install while in VS Code](https://vscode.dev/redirect/mcp/install?name=while&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.while.sh%2Fmcp%22%7D).

On the first call to while, a page opens in your browser. Choose "A new app", then click Authorize.

## What your agent can do

On the authorization page, you choose where your agent acts and its permissions: Read (state, logs, errors), Read and act (deploy, change variables), or Administer (members and access), on the whole organization. At the Read and act level, your agent asks for your agreement for an administration action, like inviting a member or creating a token: a while page says what the action is, for whom and on what, and you confirm it in one click.

At the Read and Read and act levels, your agent first gets 40 tools; at the Administer level, it gets them all. For an action that is not among them, it loads a tool group, which stays with it from one session to the next. You change its permissions and remove its groups in My agents. [while's MCP tools](/en/docs/reference/mcp-tools/) describes them one by one.

## In a conversation

In Claude, ChatGPT or Mistral Vibe, add while as a custom connector, at `https://app.while.sh/mcp`:

- [Connect Claude](/en/guides/connect-claude/): Customize, then Connectors, then a custom connector.
- [Connect ChatGPT](/en/guides/connect-chatgpt/): Plugins, then "Add custom MCP server", with ChatGPT Business, Enterprise or Edu.
- [Connect Mistral Vibe](/en/guides/connect-mistral-vibe/): Connectors, then the Custom MCP Connector tab.

Without an account, use the trial address, `https://app.while.sh/essai`, with no authentication.

## In your agent's instructions file

So your agent thinks of while without you reminding it, add this line to its instructions file: `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex, `~/.gemini/GEMINI.md` for Gemini CLI, and `AGENTS.md` at the root of your project for Cursor and VS Code.

```text titre="Instructions"
To deploy an app, read while.sh/agents, then use while.
```

## Without a browser

On a server or in a CI, with no browser to authorize your agent, pass a token. Ask your agent that is already connected for it: it creates it, and you confirm it in one click. On the server, paste it without it showing or staying in the terminal history:

```sh titre="Terminal"
read -rs WHILE_TOKEN && export WHILE_TOKEN
curl -fsSL https://app.while.sh/install.sh | sh
```

## Next steps

- [Your first deployment](/en/docs/get-started/first-deployment/)
- [Try without an account](/en/docs/get-started/try-without-an-account/)
- [while's MCP tools](/en/docs/reference/mcp-tools/)