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 -->

Author: mantrakp04

.github/workflows/db-migration-backwards-compatibility.yaml

@@ -169,6 +169,16 @@ jobs:
           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:
@@ -366,6 +376,16 @@ jobs:
           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:

.github/workflows/e2e-api-tests-local-emulator.yaml

@@ -119,6 +119,15 @@ jobs:
           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

.github/workflows/e2e-api-tests.yaml

@@ -125,6 +125,15 @@ jobs:
           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:

.github/workflows/e2e-custom-base-port-api-tests.yaml

@@ -118,6 +118,15 @@ jobs:
           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:6744/health
+          tail: true
+          wait-for: 30s
+          log-output-if: true
       - name: Start stack-dashboard in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:

apps/backend/package.json

@@ -87,7 +87,6 @@
     "@stackframe/stack-shared": "workspace:*",
     "@upstash/qstash": "^2.8.2",
     "@vercel/functions": "^2.0.0",
-    "@vercel/mcp-adapter": "^1.0.0",
     "@vercel/otel": "^1.10.4",
     "@vercel/sandbox": "^1.2.0",
     "ai": "^6.0.0",

apps/backend/src/app/api/internal/[transport]/route.ts

@@ -37,7 +37,7 @@ const buildInstallPrompt = (command: string) => deindent`
 
   ${command}
 
-  After it finishes, verify that the Stack Auth MCP server is registered in your AI client config — name: \`stack-auth\`, transport: \`http\`, URL: \`https://mcp.stack-auth.com/\`. The command above should handle this automatically; if for any reason it didn't, please add the MCP server manually so you have live access to Stack Auth docs and APIs.
+  After it finishes, verify that the Stack Auth MCP server is registered in your AI client config — name: \`stack-auth\`, transport: \`http\`, URL: \`https://mcp.stack-auth.com/mcp\`. The command above should handle this automatically; if for any reason it didn't, please add the MCP server manually so you have live access to Stack Auth docs and APIs.
 `;
 
 export default function SetupPage(props: { toMetrics: () => void }) {

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/(overview)/setup-page.tsx

@@ -164,6 +164,15 @@ <h2 style="margin-top: 64px;">Background services</h2>
           img: "https://www.svgrepo.com/show/340122/datastore.svg",
           importance: 2,
         },
+        {
+          name: "MCP",
+          portSuffix: "42",
+          description: [
+            "Src: ./apps/mcp",
+            "Prod: https://mcp.stack-auth.com/mcp",
+          ],
+          importance: 2,
+        },
         {
           name: "Demo app",
           portSuffix: "03",

apps/dev-launchpad/public/index.html

@@ -1,5 +1,6 @@
 STACK_DASHBOARD_BASE_URL=
 STACK_BACKEND_BASE_URL=
+STACK_MCP_BASE_URL=
 STACK_INTERNAL_PROJECT_ID=
 STACK_INTERNAL_PROJECT_CLIENT_KEY=
 STACK_INTERNAL_PROJECT_SERVER_KEY=

apps/e2e/.env

@@ -1,5 +1,6 @@
 STACK_DASHBOARD_BASE_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}01
 STACK_BACKEND_BASE_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02
+STACK_MCP_BASE_URL=http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}44
 STACK_INTERNAL_PROJECT_ID=internal
 STACK_INTERNAL_PROJECT_CLIENT_KEY=this-publishable-client-key-is-for-local-development-only
 STACK_INTERNAL_PROJECT_SERVER_KEY=this-secret-server-key-is-for-local-development-only