Skip to content
Docs

Deploy MCP servers to Vercel

Deploy your Model Context Protocol (MCP) servers on Vercel to take advantage of features like Vercel Functions, OAuth, and efficient scaling for AI applications.

Vercel provides the following features for production MCP deployments:

Use mcp-handler to create an MCP server in an existing Next.js App Router application. You'll need Node.js 20 or later.

Install mcp-handler v2, the MCP server SDK v2, and Zod v4:

Terminal
pnpm i mcp-handler@2.1.1 @modelcontextprotocol/server@2 zod@4
Terminal
yarn add mcp-handler@2.1.1 @modelcontextprotocol/server@2 zod@4
Terminal
npm i mcp-handler@2.1.1 @modelcontextprotocol/server@2 zod@4
Terminal
bun add mcp-handler@2.1.1 @modelcontextprotocol/server@2 zod@4

Create a route that exposes a tool for rolling an N-sided die:

app/api/mcp/route.ts
import { createMcpHandler } from 'mcp-handler';
import { z } from 'zod';
 
const handler = createMcpHandler((server) => {
  server.registerTool(
    'roll_dice',
    {
      description: 'Roll an N-sided die',
      inputSchema: z.object({ sides: z.number().int().min(2) }),
    },
    async ({ sides }) => {
      const value = 1 + Math.floor(Math.random() * sides);
      return {
        content: [{ type: 'text', text: `🎲 You rolled a ${value}!` }],
      };
    },
  );
});
 
export { handler as GET, handler as POST };

Clients connect to /api/mcp using Streamable HTTP. Your framework determines the route, so you don't need to configure a base path in mcp-handler.

Version 2 of mcp-handler uses @modelcontextprotocol/server instead of @modelcontextprotocol/sdk, changes tool registration, and removes legacy HTTP+SSE transport and Redis configuration. Follow the migration guide to update an existing server.

Start your Next.js development server at http://localhost:3000 before opening the MCP Inspector.

  1. Run the MCP inspector:
Terminal
pnpm dlx @modelcontextprotocol/inspector@latest
Terminal
yarn dlx @modelcontextprotocol/inspector@latest
Terminal
npx @modelcontextprotocol/inspector@latest
Terminal
bunx @modelcontextprotocol/inspector@latest
  1. Open the inspector interface:
    • Browse to http://127.0.0.1:6274 where the inspector runs by default
  2. Connect to your MCP server:
    • Select Streamable HTTP in the drop-down on the left
    • In the URL field, use http://localhost:3000/api/mcp
    • Expand Configuration
    • In the Proxy Session Token field, paste the token printed in the terminal where MCP Inspector is running
    • Click Connect
  3. Test the tools:
    • Click List Tools under Tools
    • Click on the roll_dice tool
    • Test it through the available options on the right of the tools section

When you deploy your application on Vercel, you will get a URL such as https://my-mcp-server.vercel.app.

Using Cursor, add the URL of your MCP server to the configuration file in Streamable HTTP transport format.

.cursor/mcp.json
{
  "mcpServers": {
    "server-name": {
      "url": "https://my-mcp-server.vercel.app/api/mcp"
    }
  }
}

You can now use your MCP roll dice tool in Cursor's AI chat or any other MCP client.

Connect your deployed MCP server to an agent so the model can discover and call its tools. Use the full Streamable HTTP endpoint, such as https://my-mcp-server.vercel.app/api/mcp, when configuring the connection.

Choose the integration for your agent framework:

  • AI SDK: Create a client with createMCPClient from @ai-sdk/mcp, retrieve the server's tools with client.tools(), and pass them to your model call. The guide includes a complete example that calls this page's roll_dice tool and closes the client when generation finishes.
  • eve: Define an MCP connection with defineMcpClientConnection under agent/connections/, using your server's endpoint and a description of its tools. eve discovers the connection from the filesystem. The guide demonstrates OAuth authentication through Vercel Connect using Linear; configure the connector and credentials for your own server when adapting it.
  • TanStack AI: Create a client with @tanstack/ai-mcp and pass it to chat() through mcp.clients. TanStack AI discovers and executes the server's tools, and connection: 'close' closes the client when the run ends. The guide uses this page's roll_dice tool.

If you enable authorization, configure the agent's MCP connection with credentials your server accepts. Model-provider credentials authenticate model requests separately. For OAuth consent and token management, use Vercel Connect.

After connecting, ask the agent to use roll_dice to roll a six-sided die. A successful tool call returns a value between one and six.

mcp-handler includes helpers for verifying bearer tokens and publishing OAuth protected resource metadata. You provide an authorization server and the logic that validates its tokens. The package does not issue tokens or run an authorization server.

Wrap your MCP handler with withMcpAuth and set required: true to require a valid token. Return the verified client's identity and scopes from verifyToken.

The following example uses a token from the MCP_DEMO_TOKEN environment variable for local testing. Set that variable in .env.local before starting your development server. For production, replace the comparison with your authorization server's token verification, including issuer, audience, expiration, and granted scopes.

Replace your MCP route with the following code:

app/api/mcp/route.ts
import type { AuthInfo } from '@modelcontextprotocol/server';
import { createMcpHandler, withMcpAuth } from 'mcp-handler';
import { z } from 'zod';
 
const handler = createMcpHandler((server) => {
  server.registerTool(
    'roll_dice',
    {
      description: 'Roll an N-sided die',
      inputSchema: z.object({ sides: z.number().int().min(2) }),
    },
    async ({ sides }) => {
      const value = 1 + Math.floor(Math.random() * sides);
      return {
        content: [{ type: 'text', text: `🎲 You rolled a ${value}!` }],
      };
    },
  );
});
 
const verifyToken = async (
  _req: Request,
  bearerToken?: string,
): Promise<AuthInfo | undefined> => {
  if (!bearerToken || bearerToken !== process.env.MCP_DEMO_TOKEN) {
    return undefined;
  }
 
  return {
    token: bearerToken,
    scopes: ['read:dice'],
    clientId: 'demo-client',
  };
};
 
const authHandler = withMcpAuth(handler, verifyToken, {
  required: true,
  requiredScopes: ['read:dice'],
  resourceMetadataPath: '/.well-known/oauth-protected-resource',
});
 
export { authHandler as GET, authHandler as POST };

With this configuration, requests without a valid token receive 401. If a verified token lacks a required scope, the handler returns 403.

To comply with the MCP specification, your server must expose a metadata endpoint that provides OAuth configuration details. Among other things, this endpoint allows MCP clients to discover how to authorize with your server, which authorization servers can issue valid tokens, and what scopes are supported.

  1. In your app/ directory, create a .well-known folder.
  2. Inside this directory, create a subdirectory called oauth-protected-resource.
  3. In this subdirectory, create a route.ts or route.js file with the following code.
  4. Replace the https://example-authorization-server-issuer.com URL with your own Authorization Server (AS) Issuer URL.
  5. Set resourceUrl to the public URL of your MCP route, including /api/mcp.
app/.well-known/oauth-protected-resource/route.ts
import {
  protectedResourceHandler,
  metadataCorsOptionsRequestHandler,
} from 'mcp-handler';
 
const handler = protectedResourceHandler({
  authServerUrls: ['https://example-authorization-server-issuer.com'],
  resourceUrl: 'https://my-mcp-server.vercel.app/api/mcp',
});
 
const corsHandler = metadataCorsOptionsRequestHandler();
 
export { handler as GET, corsHandler as OPTIONS };

To view the full list of values available to be returned in the OAuth Protected Resource Metadata JSON, see the protected resource metadata RFC.

MCP clients that are compliant with the latest version of the MCP spec can now securely connect and invoke tools defined in your MCP server, when provided with a valid OAuth token.

Each request to your MCP route runs in a Vercel Function, so the function's maximum duration limits each tool call. With Fluid compute, the default is 300 seconds on every plan. Hobby allows up to 300 seconds. Pro and Enterprise allow up to 800 seconds, or 1,800 seconds with the extended max duration beta. To raise the limit, export maxDuration from app/api/mcp/route.ts. For longer jobs, have the tool start a Vercel Workflow and return the run ID, then add a second tool that reports the run's status.

Your MCP route uses standard Vercel Functions pricing. MCP traffic tends to arrive in short bursts separated by long idle periods. With Fluid compute, one function instance can handle several requests at once. Active CPU billing pauses while your code waits on I/O, such as a model response or a database query, and provisioned memory is billed while the instance runs. If your tools call models through AI Gateway, you pay the provider's list price for tokens, with no AI Gateway markup.

Yes. createMcpHandler returns a Web-standard handler that accepts a Request and returns a Response, so it doesn't depend on Next.js or Vercel. You can mount it in a Nuxt or Nitro server handler with fromWebHandler from h3, in a SvelteKit server route, or in a Hono route by passing c.req.raw. Frameworks built on Node.js IncomingMessage and ServerResponse, such as Express, need an adapter that creates a Web Request. The /api/mcp path is a convention. mcp-handler doesn't read the request path, so you can mount it at any route and give clients that route's full URL.

Yes, if you run that code in Vercel Sandbox instead of your function. Each sandbox is a Firecracker microVM with its own filesystem and network, and the default image includes Node.js and Python. A tool can create a sandbox with @vercel/sandbox, run a command, and return a short summary to the model instead of the raw output. On Vercel, the Sandbox SDK authenticates with your project's OIDC token, so you don't add another credential. A sandbox times out after 5 minutes by default, and you can extend it to 45 minutes on Hobby or 24 hours on Pro and Enterprise. For a complete example, build a data analysis MCP server with Sandbox that runs DuckDB SQL and Python against large datasets.

Combine authorization with Vercel's network controls:

Learn how to deploy MCP servers on Vercel, connect to them using the AI SDK, and explore curated lists of public MCP servers.

Last updated September 18, 2026

Was this helpful?

supported.