Quickstart

Install your first Agent App and connect it to your AI client in under 60 seconds.

Prerequisites

You'll need:

• Node >= 20 — install
• pnpm — npm install -g pnpm
• git
• An MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot Agent Mode), or Zed

Step 1: Install Agent Apps

Clone the repo and run the installer:

git clone https://github.com/agentapps/agentapps.git
cd agentapps
./install.sh

The script installs dependencies, builds the CLI, and symlinks agentapps into /usr/local/bin.

Note: A one-command install (curl | bash) is planned but not yet available. For now, clone + install is the simplest path. The installer also configures shell tab-completion for bash and zsh.

Verify the CLI is available:

agentapps apps

You should see the full catalog — 80+ apps including Gmail, Slack, GitHub, Playwright, Notion, and more.

Step 2: Install an app

Let's install Playwright — a browser automation app that needs no authentication:

agentapps install app.playwright browser

• app.playwright — the canonical app ID
• browser — a local alias you choose (how you'll refer to this instance)

Check what tools are available:

agentapps browser tools

You'll see tools like browser-navigate, browser-click, browser-screenshot, and more.

Step 3: Connect your AI client

Agent Apps works with any MCP-compatible client through Gateway MCP — a bridge that translates between the Agent Apps protocol and MCP.

3a. Start a Station

In a terminal, start the Station server:

agentapps serve --port 4100

This serves all your installed apps over HTTP on port 4100. Keep this running.

3b. Build Gateway MCP

In another terminal, clone and build the Gateway MCP bridge:

git clone https://github.com/agentapps/gateway-mcp.git
cd gateway-mcp
npm install
npm run build

Note the absolute path to gateway-mcp/dist/index.js — you'll need it for the next step.

3c. Add Gateway MCP to your client

Pick your client below and add the configuration:

Claude Code — run this command (replace the path):

claude mcp add agentapps \
  -e CONTROLLER_URL=http://localhost:4100 \
  -e ANNOUNCE_PORT=4200 \
  -- node /absolute/path/to/gateway-mcp/dist/index.js

Or add to .mcp.json at your project root:

{
  "mcpServers": {
    "agentapps": {
      "command": "node",
      "args": ["/absolute/path/to/gateway-mcp/dist/index.js"],
      "env": {
        "CONTROLLER_URL": "http://localhost:4100",
        "ANNOUNCE_PORT": "4200"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "agentapps": {
      "command": "node",
      "args": ["/absolute/path/to/gateway-mcp/dist/index.js"],
      "env": {
        "CONTROLLER_URL": "http://localhost:4100",
        "ANNOUNCE_PORT": "4200"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Cursor — add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "agentapps": {
      "command": "node",
      "args": ["/absolute/path/to/gateway-mcp/dist/index.js"],
      "env": {
        "CONTROLLER_URL": "http://localhost:4100",
        "ANNOUNCE_PORT": "4200"
      }
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agentapps": {
      "command": "node",
      "args": ["/absolute/path/to/gateway-mcp/dist/index.js"],
      "env": {
        "CONTROLLER_URL": "http://localhost:4100",
        "ANNOUNCE_PORT": "4200"
      }
    }
  }
}

VS Code (Copilot Agent Mode) — add to .vscode/mcp.json:

⚠️ VS Code uses "servers" (not "mcpServers") and requires "type": "stdio".

{
  "servers": {
    "agentapps": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gateway-mcp/dist/index.js"],
      "env": {
        "CONTROLLER_URL": "http://localhost:4100",
        "ANNOUNCE_PORT": "4200"
      }
    }
  }
}

Requires Copilot Agent Mode (not just Chat mode) to use MCP tools.

Zed — add to ~/.config/zed/settings.json:

⚠️ Zed uses "context_servers" and nests the command in an object.

{
  "context_servers": {
    "agentapps": {
      "command": {
        "path": "node",
        "args": ["/absolute/path/to/gateway-mcp/dist/index.js"],
        "env": {
          "CONTROLLER_URL": "http://localhost:4100",
          "ANNOUNCE_PORT": "4200"
        }
      }
    }
  }
}

Settings auto-reload on save — no restart needed.

Quick reference

Step 4: Test a tool

Open your AI client and ask it to use a tool:

Navigate to example.com and take a screenshot

Your AI agent should:

1. See the Playwright tools as MCP tools (e.g. browser__browser-navigate, browser__browser-screenshot)
2. Call browser-navigate with url: https://example.com
3. Call browser-screenshot
4. Return the result

That's it. You just gave your AI agent real tools through Agent Apps.

Verify it's working

If tools don't appear in your AI client:

1. Check the Station is running:

   curl http://localhost:4100/health

2. Check Gateway MCP's announce listener:

   curl http://localhost:4200/health

3. Enable debug mode — add "DEBUG": "1" to the env config for Gateway MCP
4. Check your client's MCP server logs (most clients show stderr output)

What's happening behind the scenes

Your AI Client (Claude Code, Cursor, ...)
  │
  │  MCP protocol (stdio)
  │
  ▼
Gateway MCP
  │
  │  Agent Apps protocol (HTTP)
  │
  ▼
Station (agentapps serve --port 4100)
  │
  │  spawns & routes
  │
  ▼
App instance (Playwright)

1. Gateway MCP connects to the Station and discovers all installed apps and their tools
2. Each tool is exposed as an MCP tool with the naming convention {app}__{tool} (e.g. browser__browser-navigate)
3. When your AI agent calls a tool, Gateway MCP translates the MCP call to an Agent Apps tool_call message
4. The Station routes it to the correct app instance
5. The result comes back and is translated to an MCP response

Your AI agent doesn't know anything about Agent Apps — it just sees tools it can call.

Next steps