Per User OAuth in a Next.js MCP Server (Step by Step)
Your MCP server is using one shared API key for every caller. That works in a demo. The second you need each user to call a tool with their credentials (their GitHub token, their Notion workspace, their Stripe key) a shared key blows up. Here's how to wire per user OAuth into a Next.js MCP server so each session gets its own scoped token.
The problem with shared keys
When you build an MCP server the usual way, tools look like this:
server.tool("get-my-repos", {}, async () => {
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data } = await octokit.repos.listForAuthenticatedUser();
return { repos: data.map((r) => r.full_name) };
});
That GITHUB_TOKEN is yours. Every user who connects to this server gets results from your account. In a multitenant setup, that's a footgun. Alice calls get-my-repos and sees Bob's repos. Bob calls create-issue and writes to Alice's project.
You need each MCP session to carry its own OAuth token. Here's how to do it without reinventing the session layer.
How the token flow works
Three pieces fit together:
- NextAuth holds the user's OAuth access token in their session cookie.
- A Next.js Route Handler acts as the MCP transport. It can read the session before any tool runs.
- MCP tool context receives the token via closure (no global state, no env vars).
The key insight: your Route Handler runs in a request context, so it has full access to the session. You create the MCP server instance inside that handler, which means every tool closure captures the authenticated user's token before it runs.
Step 1: Set up NextAuth with token persistence
Install what you need:
npm install next-auth @auth/core @octokit/rest
Configure NextAuth to store the OAuth access token in the session. Critically, you need the jwt and session callbacks. By default NextAuth does not expose the raw access token to your session object:
// src/app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
export const { handlers, auth } = NextAuth({
providers: [
GitHub({
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
authorization: {
params: { scope: "repo read:user" },
},
}),
],
callbacks: {
async jwt({ token, account }) {
// `account` is only present on the initial sign-in
if (account) {
token.accessToken = account.access_token;
}
return token;
},
async session({ session, token }) {
session.accessToken = token.accessToken as string;
return session;
},
},
});
export const { GET, POST } = handlers;
And extend the session type so TypeScript doesn't complain:
// src/types/next-auth.d.ts
import { DefaultSession } from "next-auth";
declare module "next-auth" {
interface Session extends DefaultSession {
accessToken: string;
}
}
After a user signs in with GitHub, session.accessToken is their personal GitHub token scoped to repo read:user. It's stored in their encrypted session cookie, not anywhere on your server.
Step 2: The MCP Route Handler with per user context
This is the important part. Your MCP transport lives inside a Route Handler at /api/mcp:
// src/app/api/mcp/route.ts
import { createMcpHandler } from "@vercel/mcp-adapter";
import { auth } from "@/app/api/auth/[...nextauth]/route";
export const POST = async (request: Request) => {
// Read the session for THIS request
const session = await auth();
if (!session?.accessToken) {
return new Response("Unauthorized", { status: 401 });
}
// Create a new MCP handler instance for this request.
// The tool registrations close over `session` — each call gets its own.
const handler = createMcpHandler(
(server) => {
server.tool("get-my-repos", {
description: "Lists repositories the current user has access to",
inputSchema: {
type: "object",
properties: {
visibility: {
type: "string",
enum: ["all", "public", "private"],
default: "all",
},
},
},
}, async ({ visibility = "all" }) => {
const response = await fetch(
`https://api.github.com/user/repos?visibility=${visibility}&per_page=20`,
{
headers: {
Authorization: `Bearer ${session.accessToken}`,
Accept: "application/vnd.github+json",
},
}
);
if (!response.ok) {
throw new Error(`GitHub API returned ${response.status}`);
}
const repos = await response.json();
return {
content: [
{
type: "text",
text: repos
.map((r: { full_name: string; private: boolean }) =>
`${r.full_name} (${r.private ? "private" : "public"})`
)
.join("\n"),
},
],
};
});
},
{},
{ redisUrl: process.env.REDIS_URL }
);
return handler(request);
};
The session.accessToken in the tool handler is captured from the outer POST function scope. It's the token for whoever made this request. Two users hitting /api/mcp at the same moment get two separate MCP handler instances, each with their own token.
No global state. No shared credentials. Each request is isolated.
Step 3: Adding a second tool
Once the pattern is in place, adding tools is just adding more server.tool calls inside the same closure. They all get session for free:
server.tool("create-issue", {
description: "Creates a GitHub issue in a repo the current user owns",
inputSchema: {
type: "object",
required: ["repo", "title"],
properties: {
repo: { type: "string", description: "owner/repo format" },
title: { type: "string" },
body: { type: "string" },
},
},
}, async ({ repo, title, body }) => {
const [owner, repoName] = repo.split("/");
const response = await fetch(
`https://api.github.com/repos/${owner}/${repoName}/issues`,
{
method: "POST",
headers: {
Authorization: `Bearer ${session.accessToken}`,
Accept: "application/vnd.github+json",
"Content-Type": "application/json",
},
body: JSON.stringify({ title, body }),
}
);
if (!response.ok) {
const err = await response.json();
throw new Error(err.message || `GitHub API returned ${response.status}`);
}
const issue = await response.json();
return {
content: [{ type: "text", text: `Created: ${issue.html_url}` }],
};
});
This tool creates an issue on the calling user's behalf. If you'd wired this with a shared token, every issue would be created by your service account. With per user tokens, it's the actual user: their name on the issue, their rate limits, their permissions.
Verifying credential isolation
Here's a quick check before you ship. Sign in as two different GitHub accounts and grab each session cookie from the browser DevTools. Then run both calls at the same time:
# Alice's session
curl -s -X POST http://localhost:3000/api/mcp \
-H "Cookie: next-auth.session-token=<alice-token>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","id":1,"params":{"name":"get-my-repos","arguments":{}}}' \
| jq '.result.content[0].text' &
# Bob's session (run at the same time)
curl -s -X POST http://localhost:3000/api/mcp \
-H "Cookie: next-auth.session-token=<bob-token>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","id":1,"params":{"name":"get-my-repos","arguments":{}}}' \
| jq '.result.content[0].text'
You should get Alice's repos and Bob's repos in the two outputs. If both return the same list, your session isn't threading through. Check that auth() in the Route Handler is returning the right session for each request.
What to watch out for
Token expiry mid session. OAuth tokens expire. If your MCP client holds a long running session, the token can go stale between calls. Handle this by catching 401 responses from the upstream API inside your tool handlers and returning a clear error message the AI can relay to the user: "Your GitHub session expired, please sign in again."
Stateless vs stateful transports. The example above uses @vercel/mcp-adapter with a Redis URL for stateful SSE sessions. If you're using a stateless transport (plain POST with no SSE), you don't need Redis, but you also can't hold multiturn conversations over the same session. For most auth use cases, stateless is fine. You get a fresh authenticated context on every tool call.
Avoid the "just use NextAuth" trap. That's going to be the first reply to this article. Yes, NextAuth is handling the session layer here. The hard part that NextAuth does not solve for you is threading that session token into the MCP tool context specifically. That's what the closure pattern above does.
Three things to verify right now
-
console.log(session.accessToken)inside the Route Handler: should print a real token, notundefined. - Hit
/api/mcpwithout a session cookie: you should get a 401, not a 500 or a 200 with the server token. - Two concurrent users, same tool, different results. That's the definitive proof the isolation is working.
If you want a deeper look at production MCP patterns at scale, I wrote about the full enterprise architecture in my post on MCP for enterprise agents. The NebulaDesk case study in my agentic AI product work is also a good read if you are building a multitenant Next.js product on top of AI tooling.
If you want this wired up on your own stack end to end, that is exactly the kind of work I take on via my Next.js for AI products service. Alternatively if you want strategic help on the broader agentic AI architecture, my consulting engagement covers that.
Drop a comment if your setup looks different. Curious what OAuth providers people are pairing with MCP in production. Notion? Linear? Stripe? All of the above?