Connect Your AI Tool to Vercel MCP

Build an MCP client that signs in to Vercel and lists your project data.

Introduction

30 Second Summary

Connecting a new tool to your account often begins with forms or approval queues. That friction can stop a useful experiment before it reaches a real sign-in screen.

In this project, you will publish a small JSON identity file for your own command line client. Its public URL becomes an OAuth client identity that connects your tool to Vercel MCP before listing real account data.

What You'll Build

Your terminal prints real Vercel project data after you approve a consent screen branded with your tool's own name and logo.

By the end of this project, you'll have:

  • A public client identity you can open over HTTPS to confirm the metadata Vercel reads for your tool.
  • A branded consent screen that shows your client's name, logo, and hostname before you approve the connection.
  • A read-only terminal result showing the server's available tools. Your client can then print your own projects or deployments.
  • Secret Mission: An optional challenge to push your skills further.

Are there any prerequisites?

You'll need a Vercel account plus Node installed on your computer. The walkthrough covers the full connection flow, so basic comfort with browser redirects is enough.

Before We Start

Your MCP client needs a local runtime before it can begin an OAuth sign-in. Your account also needs real data for the client to read later.

Node.js supplies the runtime for your command line client. Vercel supplies the project data for your final read-only test.

This step prepares those foundations without creating metadata or connecting to the MCP server. No OAuth tokens exist at this stage.

In this step, get ready to:
  • Verify Node.js 20 or later with npm.
  • Confirm your Vercel account has data plus a public HTTPS URL.
  • Prepare a local project folder with a Git repository.
Check Node.js and npm

Node.js runs the JavaScript code for your MCP client. Its installer includes npm for managing the packages your client needs.

  • Press Cmd+Space on macOS or the Windows key on Windows to open operating system search.
  • Search for Terminal on macOS or PowerShell on Windows.
  • Press Enter to open the terminal application.
  • Check your Node.js version plus your npm version by running:
node --version
npm --version

What Do These Checks Show?

  • The first command prints the installed Node.js version.
  • The second command confirms that npm is available from your terminal.

Choose the tab that matches the output in your terminal.

✔️ I see version 20 or higher

Your Node.js runtime meets the project requirement. A version from the second command confirms that npm is ready.

ⓧ I see an older version

Your installed Node.js release is below the project requirement. A current LTS release gives you a supported runtime for this project.

  • Open the official Node.js download page.
  • Select the current LTS release.
  • Download the installer for your operating system.
  • Run the downloaded installer.
  • Allow the operating system permission request if one appears.
  • Complete the installer with its default options.
  • Close your existing terminal after the installation finishes.
  • Reopen your terminal through operating system search.
  • Repeat the two version checks shown above.

Still Seeing the Older Version?

Your terminal may still be using the path from your previous installation. Restart your computer before checking the versions again.

If the older version remains, ask for help identifying the Node.js executable your terminal uses.

ⓧ Command not found

Node.js is missing from your terminal. The official Node.js installer also installs npm.

  • Open the official Node.js download page.
  • Select the current LTS release.
  • Download the installer for your operating system.
  • Run the downloaded installer.
  • Allow the operating system permission request if one appears.
  • Complete the installer with its default options.
  • Close your existing terminal after the installation finishes.
  • Reopen your terminal through operating system search.
  • Repeat the two version checks shown above.

Commands Still Missing?

Restart your computer so the terminal can load the path added by the installer.

If the commands remain unavailable, ask for help checking your Node.js installation.

Confirm Vercel access and a public URL

A later read-only call needs an existing project or deployment. Your metadata file also needs a public HTTPS address that you control.

  • Open the official Vercel dashboard in your browser.
  • Sign in to the Vercel account you want to connect.
  • Create an account from the sign-in page if you do not have one.
  • Complete any identity-provider authorization that appears.
  • Check whether your dashboard contains at least one project.

Choose the tab that matches your dashboard.

✔️ I have a project

You're set. Your account already has data that the MCP server can return.

  • Choose a project you are comfortable reading during this project.

ⓧ My dashboard has no projects

A small starter deployment gives the later read-only call something to return. You can create one through the project creation flow in your dashboard.

  • Start a new project from your Vercel dashboard.
  • Choose a starter template from the available options.
  • Keep the generated project name.
  • Start the deployment.

The first deployment can take a few minutes while Vercel builds the template. A quiet screen during this wait is normal.

  • Wait until the dashboard reports a successful deployment.
  • Select the new project from the success screen.

Deployment Did Not Finish?

Open the deployment details to locate the first failed build step. The nearby log entry points to the part that needs attention.

If the log is unclear, ask for help interpreting the deployment failure.

  • Select your project from the Vercel dashboard.
  • Select Overview in the project navigation.
  • Find the generated deployment URL.
  • Record the public URL here: https://your-project.vercel.app.
  • Open a private browser window.
  • Paste https://your-project.vercel.app into the address bar.
  • Press Enter to load the URL.

You should see the deployed site without a Vercel sign-in screen. This proves the URL can host your public client metadata later.

Does the URL Require Sign-In?

Deployment Protection can require authentication before a generated URL loads. Choose a production domain or another deployment you control that opens publicly.

If every available URL is protected, ask for help selecting a safe public URL.

Prepare the local workspace

A code editor keeps your metadata plus client code in one workspace. Visual Studio Code also provides an integrated terminal for working inside the selected folder.

  • Press Cmd+Space on macOS or the Windows key on Windows to open operating system search.
  • Search for Visual Studio Code.
  • Press Enter.

Choose the tab that matches what happens.

✔️ Visual Studio Code opens

Your editor is ready for the local client workspace.

ⓧ Visual Studio Code is not installed

  • Open the official Visual Studio Code download page.
  • Download the installer for your operating system.
  • Run the downloaded installer.
  • Allow the operating system permission request if one appears.
  • Complete the installation with the default options.
  • Return to operating system search.
  • Search for Visual Studio Code again.
  • Press Enter to open it.

Editor Not Opening?

Restart your computer after the installation. This refreshes the application list used by operating system search.

If Visual Studio Code still does not open, ask for help verifying the installation.

Your local client needs a dedicated folder. A Git repository records the changes you make inside it.

  • Select File in the Visual Studio Code menu bar.
  • Select Open Folder.
  • Select your Desktop in the folder dialog.
  • Use the dialog's new-folder control to create vercel-mcp-client.
  • Select the new vercel-mcp-client folder.
  • Confirm the folder selection.

You should see vercel-mcp-client as the open folder in the editor sidebar.

  • Select Terminal in the Visual Studio Code menu bar.
  • Select New Terminal.
  • Check whether Git is available by running:
git --version

What Does This Check Show?

The command prints the installed Git version. A version number confirms that the terminal can access Git.

Choose the tab that matches your terminal output.

✔️ I see a Git version

Git is ready to track the files in your client workspace.

ⓧ Command not found

Git needs to be installed before you initialize the repository. The official installation guide covers each supported operating system.

  • Open the official Git installation guide.
  • Follow the installation section for your operating system.
  • Allow the operating system permission request if one appears.
  • Close Visual Studio Code after the installation finishes.
  • Reopen Visual Studio Code through operating system search.
  • Select File from the top menu.
  • Select Open Folder.
  • Open the vercel-mcp-client folder from your Desktop.
  • Repeat the Git version check shown above.

Git Still Unavailable?

Restart your computer so Visual Studio Code can load the updated terminal path.

If Git remains unavailable, ask for help checking the installation.

Before you initialize the repository, what do you expect Git to add inside vercel-mcp-client?

  • Initialize the local repository by running:
git init

What Did Git Create?

Git creates a hidden .git directory inside vercel-mcp-client. This directory stores repository history plus configuration.

You should see output beginning with Initialized empty Git repository. Your local workspace is ready for the MCP client.

Your runtime, Vercel access, public URL, editor, and local repository are ready. Next, you will publish the metadata that gives your MCP client a visible identity.

Publish Your Client Metadata

Your future MCP client needs a public identity before Vercel can show a consent screen. A Client ID Metadata Document publishes that identity at an HTTPS URL.

You will publish your logo first to establish a stable hostname. That hostname becomes part of client-metadata.json when you publish the finished OAuth identity.

In this step, get ready to:
  • Publish your client logo on a stable production hostname.
  • Create a JSON metadata document with your client identity.
  • Verify that both identity files are public without authentication.
Prepare and publish your logo

The logo must already be online before its URL can go into the metadata document. Hosting it first also gives you the hostname that becomes your client identity.

  • Switch back to the terminal in your local Git repository.
  • Create the metadata folder by running these commands:
mkdir metadata
ls

What do these commands do?

  • The first command creates the metadata folder inside your repository.
  • The second command lists the repository contents so you can confirm the folder exists.

You should see metadata in the terminal output.

  • Drag a square PNG image that you own into the metadata folder through your code editor's file sidebar.
  • Rename the copied image to logo.png.
  • Confirm the logo is inside the folder by running this command in the terminal from earlier:
ls metadata

What does this check prove?

This lists the files that Vercel receives from the metadata folder. Seeing logo.png proves the image is ready for deployment.

You should see logo.png in the output.

A Vercel production domain points to the latest production deployment. Publishing the logo now gives you a stable hostname for both identity files.

The first deployment may hand you to Vercel's browser sign-in, where your password stays out of the terminal. The command can pause while npm downloads the CLI, so a short wait is normal.

  • Approve the one-time package download if npm requests confirmation.
  • Complete the browser sign-in if the CLI requests authentication.
  • Select the Vercel account or team that owns this deployment.
  • Choose to create a new Vercel project for the metadata folder.
  • Accept the detected project settings when prompted.
  • Publish the logo to production by running these commands:
cd metadata
npx vercel@latest deploy --prod

What does this deployment do?

  • The first command moves the terminal into the folder that contains your public identity files.
  • The deployment command links that folder to a Vercel project.
  • The --prod option publishes the files to the project's production domain.

You should see a successful deployment in the terminal. Vercel also creates a production domain for the new project.

Finding the stable hostname is a little fiddly because the terminal also prints a deployment URL.

  • Return to the Vercel dashboard in your browser.
  • Select the project that the CLI created.
  • Select Settings in the project sidebar.
  • Select Domains.
  • Find the production hostname that ends in .vercel.app.
  • Record the hostname without https:// here: <your-metadata-host>.

Before you check the logo, do you expect the browser to show the image directly or ask you to sign in?

  • Open the deployed logo by entering this URL in a new browser tab:
https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/logo.png

What should you see?

Your browser should display logo.png directly. A direct image confirms that the file is available from your production hostname.

Logo not public?

  • Confirm that the filename is exactly logo.png if the browser reports that the file is missing.
  • Return to the project's Settings if the browser asks you to sign in.
  • Select Deployment Protection in the sidebar.
  • Set the protection level to None.
  • Redeploy the production files after saving the protection setting.
  • Help me troubleshoot why my Vercel logo URL is missing or requires authentication.

Good. Your client now has a public logo that the later consent screen can load.

Create the client metadata document

The client_id inside the document must match the public metadata URL exactly. The redirect URI must also match the callback address that your client uses later.

  • Create the metadata source file in the current folder by running these commands:
touch client-metadata.json
ls

What do these commands do?

  • The first command creates client-metadata.json beside logo.png.
  • The second command confirms that both source files are inside the deployment folder.

You should see client-metadata.json plus logo.png in the output.

  • Select client-metadata.json in your code editor's file sidebar.
  • Paste this metadata into the file:
{
  "client_id": "https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/client-metadata.json",
  "client_name": "My Vercel MCP Client",
  "logo_uri": "https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/logo.png",
  "redirect_uris": ["http://localhost:3000/callback"]
}

What does this metadata do?

  • The client_id value identifies your client through the metadata document's own public URL.
  • The client_name value supplies the human-readable name for the client.
  • The logo_uri value points to the public image you deployed.
  • The redirect_uris array permits the exact local callback address that your client uses later.
  • Save client-metadata.json.
  • Publish the finished metadata document by running this command in the terminal from earlier:
npx vercel@latest deploy --prod

What happens to the public hostname?

This production deployment updates the same Vercel project. Your recorded hostname now serves client-metadata.json plus logo.png.

You should see confirmation that the production deployment succeeded. The stable production domain now points to the updated files.

Metadata deployment failing?

  • Confirm that your terminal is still inside the metadata folder.
  • Check that every JSON property uses double quotes if the deployment reports invalid JSON.
  • Compare the hostname in client_id with the hostname listed under the project's Domains settings.
  • Help me diagnose why my client metadata deployment is failing.

✔️ Awesome, I've got everything!

Great. Confirm that client-metadata.json is saved inside the metadata folder.

ⓧ I'd like to double check the full code

Here is the complete client-metadata.json file:

{
  "client_id": "https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/client-metadata.json",
  "client_name": "My Vercel MCP Client",
  "logo_uri": "https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/logo.png",
  "redirect_uris": ["http://localhost:3000/callback"]
}
Verify the public identity files

Vercel must be able to fetch these files without access to your account session. A private browser window tests the same public path that the authorization server uses.

Before you check, do you expect the private window to show your JSON immediately or redirect you to a sign-in page?

  • Open a private browsing window with no active Vercel session.
  • Load the public metadata document by entering this URL:
https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/client-metadata.json

What should you see?

You should see a JSON document immediately. It should show My Vercel MCP Client as the client name.

The logo URL should use your recorded hostname. The redirect list should contain http://localhost:3000/callback.

  • Confirm that the public logo also works by entering this URL in the private window:
https://[[YOUR_METADATA_HOST="<your-metadata-host>"]]/logo.png

What should you see?

You should see your logo without a password prompt or Vercel sign-in screen. That proves both identity files are public without authentication.

You've got the identity foundation live. Vercel can now fetch your client name plus its logo from a URL you control.

Your public metadata document is ready. Next, you'll use its URL as the OAuth client_id when you build the MCP client.

Build the MCP Client

Your public metadata document gives your client an identity that Vercel MCP can read. The next gap is a local program that can begin the connection.

The Model Context Protocol client SDK discovers the authorization server. It generates the OAuth request with the PKCE values that protect the redirect.

In this step, get ready to:
  • Install the official MCP client package in your local repository.
  • Prepare OAuth state storage with a localhost callback listener.
  • Produce an authorization URL from a Vercel MCP connection.
Install the MCP client SDK

The official @modelcontextprotocol/client package provides the remote transport. It also coordinates OAuth discovery with your provider.

  • Return to the terminal tab that is already inside your local Git repository.
  • Prepare the repository as a Node.js package with the MCP client dependency by running these commands:
npm init -y
npm install @modelcontextprotocol/client

What do these commands do?

  • The npm init -y command creates a default package.json file without opening an interactive wizard.
  • The npm install @modelcontextprotocol/client command adds the client SDK to your project dependencies.

You should see a package installation summary without failed dependencies. Your repository now contains package.json, package-lock.json, and node_modules.

Seeing an installation error?

  • Return to the local Git repository before running the commands again.
  • Check your network connection if the package download stops.

Ask for help with the exact terminal output: Help me troubleshoot this MCP client package installation error.

Create the OAuth foundation

The SDK needs a provider that holds each temporary OAuth value during the running process. This provider keeps the client identity tied to the authorization request.

  • Create oauth-provider.mjs in your local Git repository by pasting the code below into a new file:
export class OAuthProvider {
  constructor(metadataUrl, onAuthorization) {
    // Bind the public identity document to this local OAuth session.
    this.clientMetadataUrl = metadataUrl
    this.redirectUrl = "http://localhost:3000/callback"
    this.onAuthorization = onAuthorization
  }

  get clientMetadata() {
    return {
      client_name: "My Vercel MCP Client",
      redirect_uris: [this.redirectUrl]
    }
  }

  // Keep OAuth flow values in memory while the command is running.
  clientInformation() { return this.clientInfo }
  saveClientInformation(info) { this.clientInfo = info }
  tokens() { return this.savedTokens }
  saveTokens(tokens) { this.savedTokens = tokens }
  state() { return (this.lastState = crypto.randomUUID()) }
  redirectToAuthorization(url) { this.onAuthorization(url) }
  saveCodeVerifier(value) { this.verifier = value }
  codeVerifier() {
    if (!this.verifier) throw new Error("Missing PKCE code verifier.")
    return this.verifier
  }
  saveDiscoveryState(value) { this.discovery = value }
  discoveryState() { return this.discovery }
}

What does this provider do?

  • The clientMetadataUrl value tells the SDK to use your public metadata document as the OAuth client ID.
  • The state() method creates a fresh value that binds the browser redirect to this process.
  • The saveCodeVerifier() method keeps the PKCE verifier available for the later token exchange.
  • The storage methods keep OAuth data in memory. This step does not write a token to disk.
  • Save oauth-provider.mjs.

You should see oauth-provider.mjs listed in your code editor sidebar.

The redirect URI points back to your machine. A small HTTP listener must be ready on port 3000 before the browser returns there.

  • Create callback-server.mjs in your local Git repository by pasting the code below into a new file:
import { createServer } from "node:http"

// Keep the loopback callback ready without exchanging a token yet.
export function startCallbackServer() {
  const server = createServer((request, response) => {
    const callback = new URL(request.url ?? "/", "http://localhost:3000")
    if (callback.pathname !== "/callback") {
      response.writeHead(404)
      response.end("Not found")
      return
    }

    response.writeHead(200, { "Content-Type": "text/plain" })
    response.end("Callback received. Return to the terminal.")
    console.log("Callback received. Token exchange is not running yet.")
  })

  server.listen(3000, () => {
    console.log("Callback listener ready at http://localhost:3000/callback")
  })
  return server
}

What does this listener do?

  • The HTTP server listens on the same http://localhost:3000/callback address published in your metadata document.
  • Requests for any other path receive a simple missing-page response.
  • The callback path confirms that the browser returned. Token exchange remains outside this step.
  • Save callback-server.mjs.

You should now see both oauth-provider.mjs and callback-server.mjs in your code editor sidebar.

Connect and print the authorization URL

The client ID is your deployed metadata document: https://<your-metadata-host>/client-metadata.json.

The entry point starts the callback listener before contacting the MCP server. This order ensures port 3000 is ready when authorization begins.

  • Create client.mjs in your local Git repository by pasting the code below into a new file:
import {
  Client,
  StreamableHTTPClientTransport,
  UnauthorizedError
} from "@modelcontextprotocol/client"
import { OAuthProvider } from "./oauth-provider.mjs"
import { startCallbackServer } from "./callback-server.mjs"

const metadataUrl = "[[METADATA_URL=\"https://<your-metadata-host>/client-metadata.json\"]]"
const serverUrl = new URL("https://mcp.vercel.com")

// Start the redirect listener before the OAuth request leaves this process.
startCallbackServer()
const provider = new OAuthProvider(metadataUrl, authorizationUrl => {
  console.log(`Authorization URL:\n${authorizationUrl.href}`)
})

const client = new Client({ name: "my-vercel-mcp-client", version: "1.0.0" })
const transport = new StreamableHTTPClientTransport(serverUrl, {
  authProvider: provider
})

// A missing token triggers discovery and prints the browser handoff URL.
try {
  await client.connect(transport)
} catch (error) {
  if (!(error instanceof UnauthorizedError)) throw error
  console.log("Authorization is ready. Leave this process running.")
}

How does the connection start?

  • The transport contacts https://mcp.vercel.com without a token. That response starts OAuth discovery.
  • The provider supplies your metadata URL as the client ID. Vercel can fetch the identity document from your host.
  • The SDK generates the PKCE challenge plus its private verifier. The authorization URL receives only the challenge.
  • The UnauthorizedError confirms that browser authorization is now required. Your code catches it after printing the handoff URL.
  • Save client.mjs.

Before you run the client, which two terminal messages would prove that the local callback and browser handoff are ready?

  • Start the command-line client by running:
node client.mjs

What should you see?

You should see Callback listener ready at http://localhost:3000/callback. This confirms that your local redirect listener owns port 3000.

You should then see an authorization URL plus Authorization is ready. Leave this process running. The URL contains your metadata address as the client ID with generated PKCE and state values.

  • Keep this terminal process running for the next step.

Missing the authorization URL?

  • Check that @modelcontextprotocol/client appears in the dependencies section of package.json if the import fails.
  • Stop the other local process with Ctrl+C if port 3000 is already occupied.
  • Confirm that your metadata URL uses HTTPS and loads without authentication if OAuth discovery stops.

Share the exact terminal output for focused help: Help me debug why my MCP client does not print an authorization URL.

✔️ Awesome, I've got everything!

Your client now starts its callback listener and prints the browser authorization link. The OAuth handoff is ready.

ⓧ I'd like to double check the full code

Here is the complete oauth-provider.mjs file.

export class OAuthProvider {
  constructor(metadataUrl, onAuthorization) {
    // Bind the public identity document to this local OAuth session.
    this.clientMetadataUrl = metadataUrl
    this.redirectUrl = "http://localhost:3000/callback"
    this.onAuthorization = onAuthorization
  }

  get clientMetadata() {
    return {
      client_name: "My Vercel MCP Client",
      redirect_uris: [this.redirectUrl]
    }
  }

  // Keep OAuth flow values in memory while the command is running.
  clientInformation() { return this.clientInfo }
  saveClientInformation(info) { this.clientInfo = info }
  tokens() { return this.savedTokens }
  saveTokens(tokens) { this.savedTokens = tokens }
  state() { return (this.lastState = crypto.randomUUID()) }
  redirectToAuthorization(url) { this.onAuthorization(url) }
  saveCodeVerifier(value) { this.verifier = value }
  codeVerifier() {
    if (!this.verifier) throw new Error("Missing PKCE code verifier.")
    return this.verifier
  }
  saveDiscoveryState(value) { this.discovery = value }
  discoveryState() { return this.discovery }
}

Here is the complete callback-server.mjs file.

import { createServer } from "node:http"

// Keep the loopback callback ready without exchanging a token yet.
export function startCallbackServer() {
  const server = createServer((request, response) => {
    const callback = new URL(request.url ?? "/", "http://localhost:3000")
    if (callback.pathname !== "/callback") {
      response.writeHead(404)
      response.end("Not found")
      return
    }

    response.writeHead(200, { "Content-Type": "text/plain" })
    response.end("Callback received. Return to the terminal.")
    console.log("Callback received. Token exchange is not running yet.")
  })

  server.listen(3000, () => {
    console.log("Callback listener ready at http://localhost:3000/callback")
  })
  return server
}

Here is the complete client.mjs file.

import {
  Client,
  StreamableHTTPClientTransport,
  UnauthorizedError
} from "@modelcontextprotocol/client"
import { OAuthProvider } from "./oauth-provider.mjs"
import { startCallbackServer } from "./callback-server.mjs"

const metadataUrl = "[[METADATA_URL=\"https://<your-metadata-host>/client-metadata.json\"]]"
const serverUrl = new URL("https://mcp.vercel.com")

// Start the redirect listener before the OAuth request leaves this process.
startCallbackServer()
const provider = new OAuthProvider(metadataUrl, authorizationUrl => {
  console.log(`Authorization URL:\n${authorizationUrl.href}`)
})

const client = new Client({ name: "my-vercel-mcp-client", version: "1.0.0" })
const transport = new StreamableHTTPClientTransport(serverUrl, {
  authProvider: provider
})

// A missing token triggers discovery and prints the browser handoff URL.
try {
  await client.connect(transport)
} catch (error) {
  if (!(error instanceof UnauthorizedError)) throw error
  console.log("Authorization is ready. Leave this process running.")
}

Your command-line client now reaches Vercel MCP with your hosted identity document. Next, you will open the link and inspect the consent screen before approving access.

Sign In Through Vercel

Your metadata document and local client are ready. The client can now generate an authorization request for Vercel MCP.

This step moves that request into the browser through OAuth. Your goal is a consent screen that shows the identity you published before you grant access.

In this step, get ready to:
  • Start the client with its callback listener waiting.
  • Complete Vercel sign-in from the authorization link.
  • Verify the consent screen displays your published client identity.
Prepare the authorization request

An OAuth client keeps its local callback listener active while the browser handles sign-in. Your client already generates the authorization link that begins this flow.

  • Switch back to the terminal from the previous step.
  • Rerun the same client start command that previously printed the authorization URL.

You should see a fresh authorization URL in the terminal. The callback listener should remain waiting at http://localhost:3000/callback.

  • Keep this terminal process running.

How Does the Request Prove Identity?

The authorization request uses your public metadata document URL as its client_id. Vercel reads that document to identify the client.

The PKCE values connect this browser session to the local client that created the request. The callback listener stays ready for the browser response.

No Authorization Link?

  • Confirm the terminal is still using the local Git repository from the previous step.
  • Stop any other local app that is already using port 3000.
  • Rerun the same client start command from the previous step.

Help me troubleshoot why my Vercel MCP client is not printing an authorization URL.

Continue in the browser

Account sign-in is the credential-sensitive moment in this step. Your credentials stay on Vercel's browser sign-in page.

  • Copy the full authorization URL printed in the terminal.
  • Record the printed value here: your printed authorization URL.
  • Open a new tab in your browser.
  • Paste your printed authorization URL into the browser address bar.
  • Load the address by pressing Enter.
  • Complete Vercel sign-in with the account that contains your project or deployment.
  • Stop on the consent screen before approving the connection.

You have cleared the sign-in checkpoint. Vercel is now showing the decision screen for your client.

Consent Screen Not Loading?

  • Confirm you pasted the complete authorization URL without missing characters.
  • Return to the terminal.
  • Confirm the client process is still waiting for the callback.

Help me troubleshoot why the Vercel authorization link is not reaching the consent screen.

Verify the consent screen

The consent screen turns your Client ID Metadata Document into visible proof of identity. Matching details confirm Vercel fetched the metadata file you published.

Before you check each detail, which parts of your published identity do you expect to recognize?

  • Compare the displayed client name with My Vercel MCP Client.
  • Compare the displayed logo with your deployed logo.png image.
  • Confirm the displayed hostname matches the host of your metadata document.
  • Leave the consent screen open without approving the connection.
  • Keep the callback listener running in the terminal.

You should see My Vercel MCP Client, the deployed logo, and your metadata hostname. Your terminal should remain waiting for the callback.

No OAuth token has been received or saved.

Identity Details Do Not Match?

  • Avoid approving the connection while any identity detail is incorrect.
  • Return to the public metadata document from earlier.
  • Confirm its published client name, logo URL, and redirect URI still match your intended values.

Help me diagnose why my Vercel consent screen does not match my published client metadata.

Your client identity now appears on a real Vercel consent screen. Next, you will approve the connection so your client can complete the token exchange.

Approve the Connection

Your consent screen now shows the identity published by your metadata document. Vercel MCP still needs your explicit approval before it returns an authorization code to the local callback.

The OAuth callback returns to your waiting client after approval. The client validates its saved state before accepting the response.

PKCE lets the client prove that it started the same sign-in request. The resulting credentials stay in a local token file that Git ignores.

In this step, get ready to:
  • Review the client identity requesting access.
  • Approve the connection through the Vercel consent screen.
  • Confirm the successful sign-in without exposing the token.
Review the client identity

The metadata hostname is the trust anchor for your client. It should point to the host where you published the metadata document.

  • Switch back to the Vercel consent screen from earlier.
  • Confirm the client name reads My Vercel MCP Client.
  • Confirm the displayed logo matches the image you published.
  • Confirm the metadata hostname matches your metadata host.
  • Review every requested permission before approving.
  • Select the Vercel account or team that this client should access.

These checks confirm that the request comes from your published metadata. You can now make an informed approval decision.

Complete the browser handoff

Approving this request gives your client the same account access as your Vercel user. You stay in control because the response returns to the local listener already running on your computer.

  • Click Allow Access on the Vercel consent screen.

Your browser should redirect to an address beginning with http://localhost:3000/callback. This handoff delivers the authorization code to your local client.

Callback page not loading?

If the browser cannot reach the local callback, the listener may have stopped. Return to the terminal from earlier and restart the same client command.

Use the newly printed authorization link because it contains fresh sign-in values. Confirm that the metadata redirect URI still matches http://localhost:3000/callback exactly.

Help me troubleshoot the local OAuth callback.

Verify the token stays local

The handoff completes when the client validates the OAuth state. It then exchanges the authorization code with its PKCE verifier.

  • Switch back to the terminal from earlier.
  • Confirm the client reports a successful sign-in to https://mcp.vercel.com.

That completes the full sign-in loop. Your own client is now authenticated with Vercel MCP.

The local token file now contains live credentials. Keep that file outside Git so it never enters a commit.

Before you run this check, do you expect the token file to appear as ignored or untracked?

  • Check the ignored files from a shell prompt inside your local Git repository by running this command:
git status -s --ignored

What does this check prove?

This check asks Git to include ignored paths in its short status view. An !! marker means an ignore rule keeps that path outside normal tracking.

You should see the local token file marked with !!. That marker confirms the credentials are excluded from the repository.

Token file not ignored?

If the token file appears as untracked, do not commit anything. Add its exact relative path to .gitignore before rerunning the check.

If the command does not inspect your repository, switch to a shell prompt inside the local Git repository from earlier. Run the check again from there.

Help me keep my OAuth token out of Git.

Your client has completed its Vercel sign-in without exposing its credentials. Next up, you will ask the authenticated server which MCP tools your connection can use.

Inspect Available Tools

Your client has already authenticated through OAuth. Its local token can now reconnect it to Vercel MCP.

Authentication proves who is connecting. The client still needs to ask the server which tools this authorized connection can use.

In this step, get ready to:
  • Complete MCP initialization after the client connects.
  • Request the available tools with tools/list.
  • Print the authorized tool names with their descriptions.
Complete MCP initialization

MCP initialization establishes the active session before the client requests server capabilities. This keeps capability requests inside the connection that has already authenticated.

  • Switch back to the client source file from the successful sign-in step.
  • Find the post-connection flow that runs after the OAuth token is loaded.
  • Update that flow so the client completes MCP initialization after the transport connects.
  • Save the client source file.

Before you rerun the client, do you expect your existing token to trigger another consent screen?

  • Rerun the client with the same terminal command you used during the successful sign-in step.

Your existing credentials should reconnect the client without repeating approval. The client should reach its initialized state without a protocol failure.

Why initialize first?

Initialization creates the MCP session used by later requests. A capability request sent before this point has no initialized session to use.

Client exits during initialization?

  • Confirm the initialization runs after the transport reports a successful connection.
  • Confirm the client loads the existing OAuth credentials before starting the connection.

Ask for help with the point where your client stops: Help me debug my MCP initialization flow..

Request the available tools

The tools/list request asks the initialized server for the tools available to this connection. Its response gives your client a concrete menu of supported capabilities.

  • Return to the initialized post-connection flow in the client source file.
  • Add a tools/list request that prints each returned tool name with its description.
  • Save the client source file.

Before you run the client, what kind of capability details do you expect the server to return?

  • Rerun the client with the same terminal command from the successful sign-in step.

You should see the available Vercel MCP tools printed in the terminal. Each entry should show a tool name with its description.

What does the tool list prove?

The response confirms that your client completed MCP initialization. It also identifies the capabilities available through this authorized connection.

No tools in the terminal?

  • Confirm that tools/list runs only after MCP initialization completes.
  • Confirm that the response formatter reads the returned tool collection.
  • Confirm that the terminal is running the saved version of your client.

Share the error without sharing credentials: Help me troubleshoot an empty MCP tool list..

Your client can now discover the tools exposed by its authorized Vercel MCP connection. Next up, you will choose a read-only tool and use it to retrieve your own Vercel data.

List Your Vercel Data

Your client has proved that its OAuth grant works. It has also discovered the tools available through Vercel MCP.

The final proof is a successful read from your account. You will call one authorized tool to print project data that belongs to you.

In this step, get ready to:
  • Select the read-only list_projects tool.
  • Add a project-listing call to your connected client.
  • Run the client to print your own Vercel project data.
Choose a read-only tool

Each tool has a schema that describes the input it accepts. Your connection's tool list is the authority for the exact schema available to your client.

  • Return to the terminal output from the previous step.
  • Find list_projects among the names printed by tools/list.
  • Confirm that its displayed input schema has no required fields.

Why Use list_projects?

The list_projects tool reads projects available to your account or authorized team. It does not create or update a project.

A recognizable project in the response proves that your consent grant reaches real account data.

Print your project data

Your initialized client already holds the authenticated MCP session. The next invocation reuses that session without copying the token into your source code.

Shape of the Tool Call

  • The tool name is list_projects.
  • The arguments value is an empty object because the displayed schema has no required fields.
  • The output handler prints the complete result as formatted JSON so each project record stays readable.
  • Switch back to the local client source in your code editor.
  • Add one tool invocation immediately after the existing tools/list logging block using the settings above.
  • Save the client source file.

Before you run it, picture the project name you expect your authorized connection to return.

  • Return to the terminal you used to start the client earlier.
  • Press the Up Arrow key to recall the same start command.
  • Press Enter to run the client.

You will first see the authorized tool list. Below it, you will see one or more project records containing a project name you recognize from your Vercel account.

Project Data Missing?

Confirm that list_projects appears in the latest tools/list response. Match the invocation input to the schema printed by your connection.

An empty result can mean the connection lacks access to the team that owns your projects. Check that the approved connection includes that team.

Help me debug my Vercel MCP tool call.

  • Return to the signed-in Vercel browser tab from earlier.
  • Confirm that a project name from the terminal matches a project in your account.

That match proves the response came from your authorized Vercel data.

You completed the full connection loop. Your client can now identify itself, obtain consent, discover tools, and read your Vercel data.

Secret mission

Audit Your MCP Client's Trust Boundaries

Run a security audit of the identity and credentials behind your MCP connection. Prove that the public metadata remains accurate while the private token stays local and outside Git.

Clean Up Your Resources

Clean Up Your Resources

Choose whether to keep your resources available, pause account access, or remove everything. The main project path costs $0, so cleanup focuses on protecting your account access.

Resources you used:

  • Authorized OAuth connection to Vercel MCP.
  • Gitignored local token file containing your OAuth credentials.
  • Public HTTPS metadata deployment at https://<your-metadata-host>/client-metadata.json.
  • Local Git repository for your Node.js command-line client.

Keep everything running

No action needed. Choose this if you are still testing your client or extending its read-only tool calls.

  • Leave the connection authorized while you continue using the client.
  • Keep the gitignored local token file private.
  • Keep the public metadata deployment available at https://<your-metadata-host>/client-metadata.json.
  • Keep the local Git repository for future development.

Pause - I'll come back to this later

Pause account access while keeping the metadata deployment and local Git repository ready for later.

  • Stop the local Node.js MCP client from its terminal if it is still running.
  • Return to your signed-in Vercel account to locate the connection named My Vercel MCP Client.
  • Revoke the connection for My Vercel MCP Client.
  • Confirm that the connection is no longer authorized.
  • Delete the gitignored local token file through your code editor's file browser.
  • Keep the public metadata deployment online for your next sign-in.
  • Keep the local Git repository so you can reconnect later.

Delete - I don't want to use this again

Remove the account connection, hosted metadata, local credentials, and local client repository.

  • Return to your signed-in Vercel account to locate the connection named My Vercel MCP Client.
  • Revoke the connection for My Vercel MCP Client.
  • Confirm that the connection is no longer authorized.
  • Delete the gitignored local token file through your code editor's file browser.
  • In the management dashboard for the service that hosts https://<your-metadata-host>/client-metadata.json, select the deployment serving that URL.
  • Use the hosting service's documented deletion control to remove that deployment.
  • Load https://<your-metadata-host>/client-metadata.json in your browser to verify the deletion.

You should no longer see the client metadata JSON at that URL.

  • Delete the local Git repository using the instructions for your operating system:

macOS

  • Use Finder to locate the folder containing your Node.js command-line client.
  • Move that folder to Trash.
  • Empty Trash to remove the local repository.
  • Return to the folder's former location in Finder to confirm it is gone.

Windows

  • Use File Explorer to locate the folder containing your Node.js command-line client.
  • Delete that folder.
  • Empty the Recycle Bin to remove the local repository.
  • Return to the folder's former location in File Explorer to confirm it is gone.

Nice Work!

Nice Work!

You did it! Your command-line AI tool now connects to Vercel MCP through a public identity document.

You've learned how to:

  • Published a JSON identity document at a public HTTPS URL. Used that document to show your client's branded identity on the consent screen.
  • Built a Node.js MCP client that completed a PKCE OAuth sign-in. Kept the issued token in a gitignored local file.
  • Listed the authorized tools available to your connection. Called a read-only tool to print your own Vercel project or deployment data.
  • Secret Mission: Tackled an optional challenge to push your skills further.

Ready to quiz yourself?