Skip to main content

Quick start

Connect the app-configurator to your instance and run your first audit in a few minutes. For ChatGPT and claude.ai there is nothing to install: both connect to a URL. Claude Desktop is the one client that installs a file.

1. Choose your account​

For a hosted remote connection, start from your assistant using the URL below. Appilot opens the Backoffice and reuses your signed-in session. The approval screen shows your account and organization before you grant access, and approving is an administrator's act: the credential it creates is the whole of what the connected client can do. Who needs which role, and how to delegate configuration without handing over an account, is in Who can configure.

You do not need to create or copy a service token for account-based approval. Local clients and instances without this feature use manual credentials, described below.

2. Connect​

The hosted endpoint (start here)​

https://mcp.appilot.space/mcp fronts the Appilot cloud. Every client below connects to a URL and asks you to approve access in Appilot. Nothing is installed and nothing needs keeping up to date.

The same walkthrough written for a non-developer reader is at appilot.space/connect.

ChatGPT, web and mobile​

  1. Open Settings, then Apps.
  2. Open Advanced settings and turn on Developer mode.
  3. Add a connector, paste https://mcp.appilot.space/mcp, and choose OAuth as the authentication method.
  4. ChatGPT opens the Appilot consent screen. Approve it there.

ChatGPT on the web cannot start a program on your machine, so this remote connector is its only route. The local server below is for clients that can.

claude.ai, web and mobile​

  1. Open Settings, then Connectors.
  2. Choose Add custom connector and paste the same URL.
  3. Approve it on the Appilot consent screen that opens.

Claude Code​

claude mcp add --transport http appilot https://mcp.appilot.space/mcp

Claude Code opens the consent screen in your browser the first time it connects.

Cursor, Codex, Antigravity​

Each takes a remote MCP server in its own configuration. Add the URL there and authorize it when the client first connects.

Choose the application, requested permissions and expiration. Read-only access is selected initially when requested. Editing, provisioning and sending issue reports are separate choices. The expiration defaults to 30 days and supports presets, a calendar date or an explicit no-expiration choice.

Review the account, organization, application, permissions and expiration, then choose Allow access. Back lets you revise the choices; Cancel connection returns without granting access. Appilot transfers the credential directly to its MCP service. No token needs to be copied or pasted into your chat.

Manage access in Service tokens. The Connections filter shows credentials created through approval. A warning appears seven days before expiration. Open a connection to renew its expiry or revoke it. Revoked access cannot be renewed.

If your deployment opens manual token consent instead, create a token using the instructions below. Paste it, choose Review connection, then confirm the organization, application and exact granted permissions. The grant is the overlap between requested permissions and the token's scopes.

The server sends its operating instructions on connect, so an agent reaching it this way knows the order to work in and the rules to respect. The app-configurator skill goes further; installing it is covered under Running it locally.

If your instance is on-premise, this endpoint cannot reach it: a deployment fronts exactly one instance, and the caller does not get to choose which, because a caller-chosen URL would make the service a relay for requests into networks it should not touch. Run your own endpoint (MCP reference) or use a local server below.

Running it locally​

Choose this for an on-premise instance, for local development against your own backend, or when you want the skill installed alongside the server.

The server is published on npm, so there is nothing to build and nothing to clone. Every client below runs the same command.

Any MCP client​

{
  "mcpServers": {
    "appilot": {
      "command": "npx",
      "args": ["-y", "appilot-mcp"],
      "env": {
        "APPILOT_BASE_URL": "https://api.appilot.space",
        "APPILOT_PAT": "appilot_pat_..."
      }
    }
  }
}

Put that in the client's own MCP configuration: ~/.cursor/mcp.json for Cursor, ~/.gemini/config/mcp_config.json for Antigravity, .mcp.json in the project for Codex, and the equivalent for anything else that speaks stdio MCP.

Claude Code​

claude mcp add appilot -- npx -y appilot-mcp

Set APPILOT_BASE_URL and APPILOT_PAT in the environment Claude Code runs in, or use the hosted endpoint above and skip the token entirely.

Claude Desktop​

Download the bundle from appilot.space/downloads and open it. Desktop runs the server locally, so it asks for the address of your Appilot backend (https://api.appilot.space for the cloud, not the MCP endpoint above) and for your service token, which it keeps in your operating system's keychain. It is not in the Claude app directory while the beta is closed, which is why the file is handed out this way.

The skill​

The server ships the app-configurator skill inside its own package, and it can install it for you:

npx -y appilot-mcp install-skill

That writes the skill into the directories the clients read, so an agent gets the working order and the rules rather than a bare tool list. npx -y appilot-mcp --help lists everything the command can do, the manifest subcommands included.

3. Point it at your instance​

Skip this if you connected to the hosted endpoint: that deployment already knows which instance it fronts, and the consent screen collected your token.

Set the connection in the MCP client's secure environment or credential store:

export APPILOT_BASE_URL="https://api.appilot.space"  # or your on-premise URL
export APPILOT_PAT="appilot_pat_..."                # the service token
export APPILOT_APP_ID="123"                         # optional default app

Do not commit service tokens. When the client has no secret store, forward the variables from its parent environment instead of writing the token into a project file.

Air-gapped (no registry access)​

A sovereign instance may have no registry access at all. Fetch the package once on a connected machine and carry the tarball in:

npm pack appilot-mcp                          # on a connected machine
npm install -g ./appilot-mcp-<version>.tgz    # inside the network

Then point the MCP entry at the installed command instead of npx:

{
  "mcpServers": {
    "appilot": {
      "command": "appilot-mcp"
    }
  }
}

The server starts and advertises its tools even before the endpoint is configured. A live call returns a clear configuration error until APPILOT_BASE_URL is available.

The static gate (validate_config) needs no network; only the server echo and live soak reach your instance.

4. Run an audit​

Ask your agent:

Audit my Appilot app's configuration.

It will discover the instance, read the content model, validate against the health contract, and return a prioritized report. Then:

Fix the critical and high findings, show me the changes first.

With a config:write token it applies the edits (the server re-validates each one) and re-runs validation to confirm they are resolved.

5. Soak the live page (optional)​

To prove selectors resolve on the real page, provide an authenticated session and ask the agent to soak:

export APPILOT_SOAK_STORAGE_STATE="/path/to/session.json"  # Playwright storageState

Soak the control selectors for app 123 against https://myapp.example.com/tasks

This catches selectors that pass every static check but are gone on the next render.

Advisory mode (no MCP)​

No server configured? Paste or export your configuration and ask the agent to review it against the contract. It cannot write or soak, but it produces the same prioritized findings and the exact edits to make.

Manual credentials for local clients and private instances​

Open Service tokens in the Backoffice. You need an administrator account. The page shows your signed-in account and organization; if sign-in is needed, it returns you to Service tokens afterwards.

  1. Choose Create token and give the connection a recognizable name.
  2. Choose Inspect only to audit, Edit configuration to apply changes, or Set up integrations to create apps, domains and widget keys.
  3. Choose the application. Select the whole organization if you need to create a new app. Reporting issues to Appilot is a separate optional permission.
  4. Choose an expiration. The default is 30 days; you can choose another duration, a calendar date, or explicitly choose no expiration. The date preview uses your local timezone.
  5. Review access, create the token, and copy it. It is shown only once.

For manual remote consent, keep its tab open and paste the token there.