> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-use.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://mcp-use.com/docs/feedback

```json
{
  "path": "/typescript/server/nextjs-drop-in",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Next.js Drop-In

> Run an MCP server inside an existing Next.js app, sharing tsconfig paths, components, and env files.

The Next.js drop-in lets you colocate an MCP server inside an existing Next.js
app — same repo, same `@/*` aliases, same shared components, same `.env` files
— without spinning up a separate project. Your Next.js routes keep working, and
a single `mcp-use dev` (or `build` / `start`) runs the MCP server beside them.

## Quick Start

Inside an existing Next.js app (App Router, `src/` layout):

<Steps>
  <Step title="Add the MCP server">
    Create an `src/mcp/` folder with a server entry:

    ```typescript src/mcp/index.ts theme={null}
    import { MCPServer, text } from "mcp-use/server";
    import z from "zod";
    import { getCurrentUser } from "@/lib/auth";

    const server = new MCPServer({
      name: "my-app-mcp",
      version: "1.0.0",
    });

    server.tool(
      {
        name: "whoami",
        description: "Return the currently signed-in user",
      },
      async () => text(JSON.stringify(await getCurrentUser()))
    );

    await server.listen();
    ```
  </Step>

  <Step title="Add scripts to package.json">
    ```json package.json theme={null}
    {
      "scripts": {
        "dev": "next dev",
        "mcp:dev": "mcp-use dev --mcp-dir src/mcp",
        "mcp:build": "mcp-use build --mcp-dir src/mcp",
        "mcp:start": "mcp-use start --mcp-dir src/mcp"
      },
      "dependencies": {
        "mcp-use": "^1",
        "next": "^15",
        "react": "^19",
        "react-dom": "^19"
      }
    }
    ```
  </Step>

  <Step title="Run it">
    ```bash theme={null}
    pnpm mcp:dev
    ```

    The MCP server comes up on `http://localhost:3000/mcp` with HMR, and
    imports like `@/lib/auth` resolve through your Next.js app's `tsconfig.json`.
  </Step>
</Steps>

## Project Layout

The convention for a drop-in:

```
my-next-app/
├── package.json
├── tsconfig.json            # "@/*": ["./src/*"]
├── next.config.js
├── src/
│   ├── app/                 # Next.js routes — untouched
│   ├── components/          # Shared React components (used by pages AND widgets)
│   ├── lib/                 # Shared server code (imported by tools)
│   └── mcp/
│       ├── index.ts         # MCP server entry
│       └── resources/       # Widgets (React components rendered in MCP clients)
│           └── my-widget/
│               └── widget.tsx
```

`src/mcp/index.ts` is auto-discovered when you pass `--mcp-dir src/mcp`. You
can override the entry with `--entry src/mcp/server.ts`.

Widgets in `src/mcp/resources/` are picked up by `mcp-use build` / `dev`
automatically — they can `import "@/components/..."` and those aliases resolve
through your app's `tsconfig.json`.

## How It Works

Three problems come up when you run an MCP server inside a Next.js project,
and the drop-in solves each automatically:

### 1. Path aliases (`@/lib/...`)

When your tool imports `@/lib/auth`, that alias is defined in the host app's
`tsconfig.json`. The CLI registers `tsx` with the project's tsconfig, so
transitive imports like `@/lib/auth` resolve through the same paths config
Next.js uses.

### 2. Next.js server-runtime modules

A helper like `src/lib/auth.ts` typically contains:

```typescript theme={null}
import "server-only";
import { headers, cookies } from "next/headers";
```

These modules are designed to throw or do nothing outside a Next.js request
context. When the CLI detects `next` in your `package.json`, it installs
runtime shims that replace the following specifiers with inert stand-ins:

| Module            | Stub behavior                                                         |
| ----------------- | --------------------------------------------------------------------- |
| `server-only`     | No-op (the import itself is the whole side effect in the real pkg).   |
| `client-only`     | No-op.                                                                |
| `next/cache`      | `revalidatePath`/`revalidateTag` no-op, `unstable_cache` returns fn.  |
| `next/headers`    | `headers()` returns empty `Headers`, `cookies()` returns empty store. |
| `next/navigation` | `redirect()`/`notFound()` still throw, so callers fail loudly.        |
| `next/server`     | Minimal `NextResponse`/`NextRequest` stubs.                           |

Shims run on both the ESM side (via a Node `module.register()` loader) and the
CJS side (via a `Module._resolveFilename` patch), so `require("server-only")`
and `import "server-only"` both route to the stub. No user configuration
needed.

### 3. Environment variables

The CLI mirrors Next.js's env-file cascade into `process.env` before your
server boots:

```
.env → .env.development → .env.local → .env.development.local
```

Later files override earlier ones. So `DATABASE_URL` from `.env.local` shows
up the same way Next.js sees it.

## Widgets inside a Next.js app

Widgets run in a browser iframe and **cannot** use server APIs, even though
they live inside the Next.js tree. The drop-in enforces this at build time —
if a widget (or a module it transitively imports) pulls in `server-only`,
`next/headers`, etc., the build fails with an actionable error:

```
Widget "user-card" imports "next/headers" (imported from src/components/navbar.tsx),
which is a Next.js server-only module. Widgets run in a browser iframe and
cannot use server APIs.

To fix:
  • Remove the import from the widget (or from any module the widget
    transitively imports)
  • If the widget needs data from next/headers, read it inside an MCP tool
    and pass the result through the widget's props
```

The right pattern is to fetch server data inside the MCP tool and pass it to
the widget via props:

```typescript src/mcp/index.ts theme={null}
import { MCPServer, widget } from "mcp-use/server";
import { getCurrentUser } from "@/lib/auth"; // uses next/headers — fine here

server.tool(
  {
    name: "show-profile",
    widget: { name: "profile-card" },
  },
  async () =>
    widget({
      props: { user: await getCurrentUser() },
      message: "Profile rendered",
    })
);
```

Tailwind automatically scans `<project>/src/` when it exists, so widgets that
import shared components pick up the same design tokens your app uses.

## CLI Flags

These work on `dev`, `build`, and `start`:

| Flag                  | Description                                                                     |
| --------------------- | ------------------------------------------------------------------------------- |
| `--mcp-dir <dir>`     | Folder holding the MCP entry + `resources/` (e.g. `src/mcp`).                   |
| `--entry <file>`      | Explicit entry file, relative to project root. Overrides `--mcp-dir` discovery. |
| `--widgets-dir <dir>` | Widgets directory (defaults to `<mcp-dir>/resources`).                          |

Entry file discovery in `--mcp-dir` mode tries, in order:
`<dir>/index.ts`, `<dir>/index.tsx`, `<dir>/server.ts`, `<dir>/server.tsx`.

## Build semantics

`mcp-use build --mcp-dir` is intentionally **lighter** than the standalone
build:

* **No esbuild transpile step.** The host Next.js app owns its build; trying
  to transpile every `.ts`/`.tsx` in a Next project blows up on files like
  `tailwind.config.ts` and RSC-only files. The manifest records the `.ts`
  source path and `mcp-use start` runs it through `tsx` directly.
* **No `tsc --noEmit` typecheck.** `next build` already does this for you.
* Widget builds still run — they produce static assets in
  `dist/resources/widgets/<name>/`.

## Running alongside Next.js

The MCP server and `next dev` are two separate processes. Give them different
ports:

```json package.json theme={null}
{
  "scripts": {
    "dev": "next dev",
    "mcp:dev": "mcp-use dev --mcp-dir src/mcp --port 3001"
  }
}
```

Or run them together with [concurrently](https://www.npmjs.com/package/concurrently):

```json theme={null}
{
  "scripts": {
    "dev:all": "concurrently \"next dev\" \"mcp-use dev --mcp-dir src/mcp --port 3001\""
  }
}
```

## Requirements

* Next.js 13+ (App Router or Pages Router — the shims cover both).
* A project-root `tsconfig.json` with your `@/*` paths. The drop-in picks these
  up via Vite's `resolve.tsconfigPaths` (for widgets) and `tsx`'s tsconfig
  support (for the server).
* `tailwindcss` in your `dependencies` if you use it in widgets (`@tailwindcss/vite`
  alone is not enough — the widget pipeline needs `tailwindcss` directly
  resolvable from the project).

## Example

A complete working example lives in the repo:
[examples/server/features/nextjs-drop-in](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/features/nextjs-drop-in).
It demonstrates `@/*` aliases, `server-only` + `next/headers` via a shared
`src/lib/server-data.ts`, and a widget that reuses a shared
`@/components/card` component.