stack/.github/workflows/e2e-api-tests.yaml
Mantra 647883c7ac
Move MCP server into a standalone apps/mcp app (#1405)
## Summary

Splits the Stack Auth MCP server out of `apps/backend` and into a
dedicated Next.js app at `apps/mcp/`, served on port `:42` (suffixed via
`NEXT_PUBLIC_STACK_PORT_PREFIX`) and exposed in production at
`https://mcp.stack-auth.com/mcp`. The backend no longer carries the MCP
transport route; clients now point at the new host.

Base: `dev` → Head: `chore/move-mcp-to-a-sep-app`
Scope: 34 files, +1425 / −353

## What changed

- **New app** `apps/mcp/` — standalone Next.js + `@vercel/mcp-adapter`,
with:
- `src/app/api/internal/[transport]/route.ts` — MCP transport handler
(moved from backend)
- `src/app/mcp/route.ts`, `src/app/route.ts` — public landing + setup
page
  - `src/app/health/route.ts` — health check
  - `src/mcp-handler.ts`, `src/setup-page.ts`, `src/analytics.ts`
- **Backend** drops
`apps/backend/src/app/api/internal/[transport]/route.ts` (−105) — MCP
code is gone from the backend image.
- **Dashboard** install hint updated to point at
`https://mcp.stack-auth.com/mcp` (was `/`).
- **Dev launchpad** gets an MCP tile so the new service shows up
alongside the rest of the local stack.
- **CI** workflows (`db-migration-backwards-compatibility`,
`e2e-api-tests*`) start the MCP service in the background before running
tests.
- **Docs** (`docs-mintlify`, `docs/`) and `init-stack` / `init-prompt`
updated to reference the new URL.
- **E2E** `apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts`
reworked to hit the new host; `helpers.ts` and env files gain an MCP
base-URL var.

## Visuals

### New `apps/mcp` setup page (`https://mcp.stack-auth.com/`)

The standalone app's root now serves a self-contained MCP setup guide
with per-client instructions (Cursor, VS Code, Codex, Claude Code,
Claude Desktop, Windsurf, ChatGPT, Gemini CLI):

![MCP setup
page](https://gist.githubusercontent.com/mantrakp04/892b45cb1b4e0d65d6c73a0c8771fe7d/raw/mcp-setup-page.png)

### Dev launchpad now lists the MCP service

New tile at port suffix `:42`, importance 2, alongside Backend /
Dashboard / Demo app:

![Dev launchpad with MCP
tile](https://gist.githubusercontent.com/mantrakp04/892b45cb1b4e0d65d6c73a0c8771fe7d/raw/launchpad-light-full.png)

## Notes for reviewers

- The MCP transport endpoint moved path: it was mounted under
`/api/internal/[transport]` in the backend; in the new app it's at the
same path but on the dedicated host. The public-facing URL is
`https://mcp.stack-auth.com/mcp`.
- `apps/mcp` ships its own PostHog analytics client (`src/analytics.ts`)
so the backend doesn't have to proxy events for it anymore.
- Port allocation: `${PORT_PREFIX}42` (default `8142` in dev). Picked to
fit the existing dev-launchpad importance-2 row.
- No DB migrations.

## Test plan

- [x] `apps/mcp` builds and `pnpm dev` serves on `:8142`
- [x] Dev launchpad renders the new MCP tile (screenshot above)
- [x] MCP setup page renders client tabs (screenshot above)
- [x] E2E `mcp.test.ts` updated to hit the new host
- [ ] CI green on `e2e-api-tests*` and
`db-migration-backwards-compatibility` workflows (they were touched to
start the MCP service)
- [ ] `init-stack` / `mcp.ts` install flow lands users on the new URL


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Standalone MCP app added with a public /mcp endpoint and health check.
  * MCP appears in the dev-launchpad apps list.

* **Documentation**
* MCP endpoint updated to https://mcp.stack-auth.com/mcp in all setup
guides and installer snippets.
* Setup page enhanced with detailed client install tabs and
instructions.

* **Chores**
  * MCP service integrated into CI/e2e workflows and local env configs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-05-07 15:22:44 -07:00

194 lines
7.0 KiB
YAML

name: Runs E2E API Tests
on:
push:
branches:
- main
- dev
pull_request:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
jobs:
build:
name: E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }})
runs-on: ubicloud-standard-8
env:
NODE_ENV: test
STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
STACK_RUN_SETUP_WIZARD_TESTS: ${{ matrix.freestyle-mode != 'prod' && 'true' || '' }}
strategy:
matrix:
node-version: [22.x]
freestyle-mode: [mock, prod]
steps:
- uses: actions/checkout@v6
- name: Setup Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v6
with:
node-version: ${{ matrix.node-version }}
- name: Setup pnpm
uses: pnpm/action-setup@v4
# Even just starting the Docker Compose as a daemon is slow because we have to download and build the images
# so, we run it in the background
- name: Start Docker Compose in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: docker compose -f docker/dependencies/docker.compose.yaml up --pull always -d &
# we don't need to wait on anything, just need to start the daemon
wait-on: /dev/null
tail: true
wait-for: 3s
log-output-if: true
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Create .env.test.local file for apps/backend
run: cp apps/backend/.env.development apps/backend/.env.test.local
- name: Override Freestyle API key for prod mode
if: matrix.freestyle-mode == 'prod'
run: |
echo "STACK_FREESTYLE_API_KEY=${{ secrets.STACK_FREESTYLE_REAL_API_KEY }}" >> apps/backend/.env.test.local
- name: Create .env.test.local file for apps/dashboard
run: cp apps/dashboard/.env.development apps/dashboard/.env.test.local
- name: Create .env.test.local file for apps/e2e
run: cp apps/e2e/.env.development apps/e2e/.env.test.local
- name: Create .env.test.local file for docs
run: cp docs/.env.development docs/.env.test.local
- name: Create .env.test.local file for examples/cjs-test
run: cp examples/cjs-test/.env.development examples/cjs-test/.env.test.local
- name: Create .env.test.local file for examples/demo
run: cp examples/demo/.env.development examples/demo/.env.test.local
- name: Create .env.test.local file for examples/docs-examples
run: cp examples/docs-examples/.env.development examples/docs-examples/.env.test.local
- name: Create .env.test.local file for examples/e-commerce
run: cp examples/e-commerce/.env.development examples/e-commerce/.env.test.local
- name: Create .env.test.local file for examples/middleware
run: cp examples/middleware/.env.development examples/middleware/.env.test.local
- name: Create .env.test.local file for examples/supabase
run: cp examples/supabase/.env.development examples/supabase/.env.test.local
- name: Create .env.test.local file for examples/convex
run: cp examples/convex/.env.development examples/convex/.env.test.local
- name: Create .env.test.local file for apps/internal-tool
run: cp apps/internal-tool/.env.development apps/internal-tool/.env.test.local
- name: Build
run: pnpm build
- name: Wait on Postgres
run: pnpm run wait-until-postgres-is-ready:pg_isready
- name: Wait on Inbucket
run: pnpm exec wait-on tcp:localhost:8129
- name: Wait on Svix
run: pnpm exec wait-on tcp:localhost:8113
- name: Wait on QStash
run: pnpm exec wait-on tcp:localhost:8125
- name: Wait on ClickHouse
run: pnpm exec wait-on http://localhost:8136/ping
- name: Initialize database
run: pnpm run db:init
- name: Start stack-backend in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: pnpm run start:backend --log-order=stream &
wait-on: |
http://localhost:8102
tail: true
wait-for: 30s
log-output-if: true
- name: Start stack-mcp in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: pnpm run start:mcp --log-order=stream &
wait-on: |
http://localhost:8144/health
tail: true
wait-for: 30s
log-output-if: true
- name: Start stack-dashboard in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: pnpm run start:dashboard --log-order=stream &
wait-on: |
http://localhost:8101
tail: true
wait-for: 30s
log-output-if: true
- name: Start mock-oauth-server in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: pnpm run start:mock-oauth-server --log-order=stream &
wait-on: |
http://localhost:8102
tail: true
wait-for: 30s
log-output-if: true
- name: Start run-email-queue in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: pnpm -C apps/backend run run-email-queue --log-order=stream &
wait-on: |
http://localhost:8102
tail: true
wait-for: 30s
log-output-if: true
- name: Start run-cron-jobs in background
uses: JarvusInnovations/background-action@v1.0.7
with:
run: pnpm -C apps/backend run run-cron-jobs:test --log-order=stream &
wait-on: |
http://localhost:8102
tail: true
wait-for: 30s
log-output-if: true
- name: Wait 10 seconds
run: sleep 10
- name: Run tests
run: pnpm test run ${{ matrix.freestyle-mode == 'prod' && '--min-workers=1 --max-workers=1' || '' }} ${{ matrix.freestyle-mode == 'prod' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' && 'mail' || '' }}
- name: Run tests again (attempt 1)
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
run: pnpm test run ${{ matrix.freestyle-mode == 'prod' && '--min-workers=1 --max-workers=1' || '' }}
- name: Run tests again (attempt 2)
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
run: pnpm test run ${{ matrix.freestyle-mode == 'prod' && '--min-workers=1 --max-workers=1' || '' }}
- name: Verify data integrity
run: pnpm run verify-data-integrity --no-bail
- name: Print Docker Compose logs
if: always()
run: docker compose -f docker/dependencies/docker.compose.yaml logs