OpenAI

Installation

xmcp can work on top of your existing Next.js project. To get started, run the following command in your project directory:

npx init-xmcp@latest

On initialization, you'll see the following prompts:

? Tools directory path: (tools)
? Prompts directory path: (prompts)
? Resources directory path: (resources)
? Route directory path: (app/mcp)

The package manager and framework will be detected automatically.

After setting up the project, your build and dev commands should look like this:

{
  "scripts": {
    "dev": "xmcp dev & next dev",
    "build": "xmcp build && next build"
  }
}

Before using the @xmcp/adapter import, you need to:

Run npx xmcp build to generate the .xmcp folder
Update your tsconfig.json to include the path mapping:

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@xmcp/*": ["./.xmcp/*"]
    }
  }
}

After these steps, TypeScript errors will be resolved.

Based on your configuration, it will create the tools, prompts, resources and route folders and add an endpoint to your Next.js app.

app/mcp/route.ts

import { xmcpHandler } from "@xmcp/adapter";

export { xmcpHandler as GET, xmcpHandler as POST };

middleware.ts and xmcp/headers are not supported since Next.js already supports those features.

Authentication

You can use the withAuth function to add authentication to your MCP server.

app/mcp/route.ts

import { xmcpHandler, withAuth, VerifyToken } from "@xmcp/adapter";

/**
 * Verify the bearer token and return auth information
 * In a real implementation, this would validate against your auth service
 */
const verifyToken: VerifyToken = async (req: Request, bearerToken?: string) => {
  if (!bearerToken) return undefined;

  // TODO: Replace with actual token verification logic
  // This is just an example implementation
  const isValid = bearerToken.startsWith("__TEST_VALUE__");

  if (!isValid) return undefined;

  return {
    token: bearerToken,
    scopes: ["read:messages", "write:messages"],
    clientId: "example-client",
    extra: {
      userId: "user-123",
      // Add any additional user/client information here
      permissions: ["user"],
      timestamp: new Date().toISOString(),
    },
  };
};

const options = {
  verifyToken,
  required: true,
  requiredScopes: ["read:messages"],
  resourceMetadataPath: "/.well-known/oauth-protected-resource",
};

const handler = withAuth(xmcpHandler, options);

export { handler as GET, handler as POST };

Next.js

Installation

Authentication

One framework to rule them all