🚀

What is MCP?

MCP (Model Context Protocol) is a way to give AI assistants access to your application’s data and functionality. Think of it as creating “tools” that an AI can use to help users.

Simple Analogy:

• Your app is like a toolbox 🧰
• MCP tools are like individual tools (hammer, screwdriver, etc.)
• The AI is like a smart assistant that knows which tool to use

---

🎯 What We’ll Build

A simple “Hello World” MCP server that:

1. Has a basic API endpoint
2. Provides data to an AI assistant
3. Lets the AI answer questions about your app

Time to complete: 15 minutes ⏱️

---

📋 Prerequisites

You need:

• ✅ Node.js 18+ installed
• ✅ Basic knowledge of JavaScript/TypeScript
• ✅ A text editor (VS Code recommended)
• ✅ Terminal/Command line access

---

🏗️ Step-by-Step Tutorial

Step 1: Create a New Next.js Project

# Create a new Next.js app
npx create-next-app@latest my-mcp-app

# When prompted, choose:
# ✅ TypeScript: Yes
# ✅ ESLint: Yes
# ✅ Tailwind CSS: Yes
# ✅ src/ directory: No
# ✅ App Router: Yes (IMPORTANT!)
# ✅ Turbopack: No
# ✅ Import alias: Yes (@/*)

# Navigate to the project
cd my-mcp-app

What just happened?

• Created a new Next.js project with App Router
• App Router is needed for MCP (uses /app directory)

---

Step 2: Enable MCP in Next.js Config

Open next.config.ts and enable MCP:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    // Enable MCP server
    mcp: {
      enabled: true,
      port: 3000,
    },
  },
};

export default nextConfig;

What does this do?

• Enables the MCP server in Next.js
• Sets the port to 3000 (default)

---

Step 3: Create Your First MCP Endpoint

Create a simple API endpoint that returns data:

# Create the API directory structure
mkdir -p app/api/hello

Create app/api/hello/route.ts:

// app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  // This is your data that the AI can access
  const data = {
    message: "Hello from MCP!",
    timestamp: new Date().toISOString(),
    tips: [
      "MCP lets AI access your app data",
      "You can create multiple endpoints",
      "AI can call these endpoints automatically"
    ]
  };
  
  return NextResponse.json(data);
}

What does this do?

• Creates an API endpoint at /api/hello
• Returns JSON data that includes a message and tips
• This data will be available to the AI

---

Step 4: Test Your Endpoint

Start the development server:

npm run dev

Open your browser and visit:

http://localhost:3000/api/hello

You should see:

{
  "message": "Hello from MCP!",
  "timestamp": "2025-10-25T00:00:00.000Z",
  "tips": [
    "MCP lets AI access your app data",
    "You can create multiple endpoints",
    "AI can call these endpoints automatically"
  ]
}

✅ Success! Your first MCP endpoint is working!

---

Step 5: Install AI SDK

Now let’s add AI capabilities:

# Install Vercel AI SDK and OpenAI
npm install ai @ai-sdk/openai zod

What are these packages?

• ai – Vercel AI SDK for building AI apps
• @ai-sdk/openai – OpenAI integration
• zod – Schema validation (for tool parameters)

---

Step 6: Create MCP Tools

Create a file to define your MCP tools:

# Create lib directory
mkdir -p lib

Create lib/mcp-tools.ts:

// lib/mcp-tools.ts
import { tool } from 'ai';
import { z } from 'zod';

// Define your MCP tools
export const mcpTools = {
  // Tool 1: Get hello message
  get_hello_message: tool({
    description: 'Get a hello message from the server',
    parameters: z.object({}), // No parameters needed
    execute: async () => {
      // Fetch data from your API
      const response = await fetch('http://localhost:3000/api/hello');
      const data = await response.json();
      return data;
    },
  }),
  
  // Tool 2: Get current time
  get_current_time: tool({
    description: 'Get the current server time',
    parameters: z.object({}),
    execute: async () => {
      return {
        time: new Date().toLocaleTimeString(),
        date: new Date().toLocaleDateString(),
        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
      };
    },
  }),
};

What does this do?

• Defines 2 tools that the AI can use
• get_hello_message – Fetches data from your API
• get_current_time – Returns current time
• Each tool has a description (tells AI what it does)
• Each tool has parameters (inputs the AI can provide)
• Each tool has an execute function (what it actually does)

---

Step 7: Create AI Chat Endpoint

Create app/api/chat/route.ts:

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { mcpTools } from '@/lib/mcp-tools';

export async function POST(request: Request) {
  // Get the user's message
  const { messages } = await request.json();
  
  // Call OpenAI with MCP tools
  const result = await streamText({
    model: openai('gpt-4o-mini'),
    messages,
    tools: mcpTools, // Give AI access to your tools
    maxSteps: 5, // Allow AI to use multiple tools
  });
  
  // Stream the response back to the user
  return result.toDataStreamResponse();
}

What does this do?

• Creates a chat endpoint at /api/chat
• Connects to OpenAI’s GPT-4o-mini model
• Gives the AI access to your MCP tools
• Streams responses back to the user in real-time

---

Step 8: Create a Simple Chat UI

Create app/page.tsx:

// app/page.tsx
'use client';

import { useChat } from 'ai/react';

export default function Home() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();

  return (
    <div className="flex flex-col h-screen max-w-2xl mx-auto p-4">
      <h1 className="text-3xl font-bold mb-4">Hello World MCP Chat</h1>
      
      {/* Messages */}
      <div className="flex-1 overflow-y-auto mb-4 space-y-4">
        {messages.map((message) => (
          <div
            key={message.id}
            className={`p-4 rounded-lg ${
              message.role === 'user'
                ? 'bg-blue-500 text-white ml-auto'
                : 'bg-gray-200 text-black'
            } max-w-[80%]`}
          >
            <p className="font-semibold mb-1">
              {message.role === 'user' ? 'You' : 'AI'}
            </p>
            <p>{message.content}</p>
            
            {/* Show which tools were used */}
            {message.toolInvocations && message.toolInvocations.length > 0 && (
              <div className="mt-2 text-xs opacity-75">
                🔧 Used tools: {message.toolInvocations.map(t => t.toolName).join(', ')}
              </div>
            )}
          </div>
        ))}
        
        {isLoading && (
          <div className="bg-gray-200 text-black p-4 rounded-lg">
            <p className="animate-pulse">AI is thinking...</p>
          </div>
        )}
      </div>
      
      {/* Input */}
      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Ask me anything..."
          className="flex-1 p-3 border rounded-lg"
        />
        <button
          type="submit"
          disabled={isLoading}
          className="px-6 py-3 bg-blue-500 text-white rounded-lg hover:bg-blue-600 disabled:opacity-50"
        >
          Send
        </button>
      </form>
    </div>
  );
}

What does this do?

• Creates a simple chat interface
• Shows messages from user and AI
• Displays which MCP tools the AI used
• Has an input field to type messages

---

Step 9: Add Your OpenAI API Key

Create .env.local:

# .env.local
OPENAI_API_KEY=your_api_key_here

How to get an API key:

1. Go to https://platform.openai.com/api-keys
2. Sign in or create an account
3. Click “Create new secret key”
4. Copy the key and paste it in .env.local

⚠️ Important: Never commit .env.local to git!

---

Step 10: Test Your MCP Chat!

1. Start the server:

npm run dev

2. Open your browser:

http://localhost:3000

3. Try these questions:

Question 1:

What's the hello message?

AI Response:

The hello message is "Hello from MCP!" 
Here are some tips:
- MCP lets AI access your app data
- You can create multiple endpoints
- AI can call these endpoints automatically

🔧 Used tools: get_hello_message

Question 2:

What time is it?

AI Response:

The current time is 12:34:56 PM
Date: October 25, 2025
Timezone: America/New_York

🔧 Used tools: get_current_time

🎉 Congratulations! Your MCP server is working!

---

🎨 Visual Flow

/api/helloMCP ToolsOpenAI/api/chatChat UIUser/api/helloMCP ToolsOpenAI/api/chatChat UIUser"What's the hello message?"POST /api/chatSend message + toolsDecide to use get_hello_messageCall get_hello_message()GET /api/hello{message, tips}Return dataGenerate responseStream responseServer-Sent EventsShow formatted response

---

📁 Final Project Structure

my-mcp-app/
├── app/
│   ├── api/
│   │   ├── hello/
│   │   │   └── route.ts          # Your data endpoint
│   │   └── chat/
│   │       └── route.ts          # AI chat endpoint
│   ├── page.tsx                  # Chat UI
│   └── layout.tsx                # Layout (auto-generated)
├── lib/
│   └── mcp-tools.ts              # MCP tools definition
├── .env.local                    # OpenAI API key (don't commit!)
├── next.config.ts                # MCP enabled here
├── package.json
└── tsconfig.json

---

🧪 Testing Your MCP Server

Test 1: API Endpoint

curl http://localhost:3000/api/hello

Expected output:

{
  "message": "Hello from MCP!",
  "timestamp": "2025-10-25T00:00:00.000Z",
  "tips": [...]
}

Test 2: Chat with AI

Open http://localhost:3000 and ask:

• “What’s the hello message?”
• “What time is it?”
• “Tell me about MCP”

---

🎯 Understanding the Key Concepts

1. MCP Endpoint (API Route)

// app/api/hello/route.ts
export async function GET() {
  return NextResponse.json({ message: "Hello!" });
}

What it does:

• Provides data that AI can access
• Just a regular Next.js API route
• Returns JSON data

2. MCP Tool

// lib/mcp-tools.ts
export const mcpTools = {
  my_tool: tool({
    description: 'What this tool does',
    parameters: z.object({}),
    execute: async () => {
      // Your code here
      return { result: "data" };
    },
  }),
};

What it does:

• Tells AI what the tool does (description)
• Defines what inputs it needs (parameters)
• Implements the actual functionality (execute)

3. AI Chat Endpoint

// app/api/chat/route.ts
const result = await streamText({
  model: openai('gpt-4o-mini'),
  messages,
  tools: mcpTools, // Give AI your tools
});

What it does:

• Connects to OpenAI
• Gives AI access to your MCP tools
• Streams responses back to user

---

🚀 Next Steps: Expanding Your MCP Server

Add More Tools

// lib/mcp-tools.ts
export const mcpTools = {
  // Existing tools...
  
  // New tool: Get weather
  get_weather: tool({
    description: 'Get weather for a city',
    parameters: z.object({
      city: z.string().describe('City name'),
    }),
    execute: async ({ city }) => {
      // Call weather API
      return { city, temp: 72, condition: 'Sunny' };
    },
  }),
  
  // New tool: Calculate
  calculate: tool({
    description: 'Perform basic math calculations',
    parameters: z.object({
      operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
      a: z.number(),
      b: z.number(),
    }),
    execute: async ({ operation, a, b }) => {
      switch (operation) {
        case 'add': return { result: a + b };
        case 'subtract': return { result: a - b };
        case 'multiply': return { result: a * b };
        case 'divide': return { result: a / b };
      }
    },
  }),
};

Add More Endpoints

// app/api/users/route.ts
export async function GET() {
  return NextResponse.json({
    users: [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' },
    ]
  });
}

// Then create a tool to access it
get_users: tool({
  description: 'Get list of users',
  parameters: z.object({}),
  execute: async () => {
    const res = await fetch('http://localhost:3000/api/users');
    return await res.json();
  },
}),

---

🐛 Common Issues & Solutions

Issue 1: “OpenAI API key not configured”

Solution:

# Make sure .env.local exists
echo "OPENAI_API_KEY=sk-your-key" > .env.local

# Restart the server
npm run dev

Issue 2: “Module not found: Can’t resolve ‘ai'”

Solution:

# Install the AI SDK
npm install ai @ai-sdk/openai zod

Issue 3: “MCP not enabled”

Solution:

// Check next.config.ts
const nextConfig: NextConfig = {
  experimental: {
    mcp: {
      enabled: true, // Make sure this is true
      port: 3000,
    },
  },
};

Issue 4: “fetch failed” when calling tools

Solution:

// Use full URL in tools
execute: async () => {
  // ❌ Wrong
  const res = await fetch('/api/hello');
  
  // ✅ Correct
  const res = await fetch('http://localhost:3000/api/hello');
  return await res.json();
}

---

🤔 Wait… What’s the Difference Between API Endpoints and MCP Tools?

Great question! This confuses many beginners. Let me clarify:

They ARE Similar, But Serve Different Purposes

API Endpoint = The actual data source (like a kitchen)

// app/api/hello/route.ts
export async function GET() {
  return NextResponse.json({ message: "Hello" });
}

• 🔧 Provides raw data
• 📡 Anyone can call it via HTTP
• 🌐 URL: http://localhost:3000/api/hello
• 📦 Returns JSON directly

MCP Tool = AI’s way to access that data (like a waiter)

// lib/mcp-tools.ts
get_hello: tool({
  description: 'Get hello message',
  execute: async () => {
    // Calls the API endpoint
    const res = await fetch('http://localhost:3000/api/hello');
    return await res.json();
  },
})

• 🤖 Makes API accessible to AI
• 📝 Has description AI can understand
• 🎯 AI decides when to use it
• ✨ Formats data for AI processing

Visual Comparison

With MCP (AI-Powered)Natural LanguageDecides to useCallsReturns dataStructured dataNatural ResponseUserOpenAIMCP ToolAPI EndpointWithout MCP (Regular API)HTTP RequestRaw JSONUserAPI Endpoint

Real Example: The Difference

Scenario: Get user information

1. Direct API Call (No AI):

curl http://localhost:3000/api/users
# Returns: {"users": [{"id": 1, "name": "Alice", "age": 30}]}

2. Through MCP Tool (With AI):

User: "Who are the users and how old are they?"

AI: (uses get_users tool automatically)
    → Calls /api/users
    → Gets data
    → Processes it
    → Responds naturally

AI: "There are 2 users:
     - Alice is 30 years old
     - Bob is 25 years old"

Key Differences Table

Aspect	API Endpoint	MCP Tool
What it is	HTTP route	Function wrapper
Who calls it	Anyone (HTTP)	Only AI
How to call	fetch(), curl	AI decides automatically
Response	Raw JSON	Processed by AI
Purpose	Serve data	Give AI capabilities
Reusable	Yes, by anyone	Only by AI

Why Do You Need BOTH?

API Endpoint:

• ✅ The actual data source
• ✅ Can be used by other parts of your app
• ✅ Can be tested independently
• ✅ Follows REST conventions
• ✅ Can be cached and secured

MCP Tool:

• ✅ Tells AI what the endpoint does
• ✅ Provides context (description)
• ✅ Defines parameters AI can use
• ✅ Allows AI to use it intelligently
• ✅ Makes your app AI-powered

Restaurant Analogy

API Endpoint = Kitchen

• Has the actual food (data)
• Anyone can order from it
• Returns raw dishes

MCP Tool = Waiter

• Knows what’s available (description)
• Takes your order (parameters)
• Gets food from kitchen (calls API)
• Serves it nicely (formats response)

AI = Smart Waiter

• Understands what you want
• Knows which dishes to recommend
• Can combine multiple dishes
• Explains the menu in your language

The Complete Flow

Your DataAPI EndpointMCP ToolOpenAIUserYour DataAPI EndpointMCP ToolOpenAIUserAI reads tool descriptionsDecides to use get_hello_messageAI processes & formats"What's the hello message?"execute()GET /api/helloFetch dataReturn dataJSON responseStructured data"The hello message is..."

Can You Skip the API Endpoint?

Short answer: Yes, but not recommended!

// ❌ MCP Tool without API (works but not ideal)
get_data: tool({
  execute: async () => {
    // Directly query database
    const data = await db.query('SELECT * FROM users');
    return data;
  },
})

// ✅ Better: MCP Tool + API (recommended)
get_data: tool({
  execute: async () => {
    // Call your API
    const res = await fetch('http://localhost:3000/api/users');
    return await res.json();
  },
})

Why separate API is better:

• ✅ Reusable by other parts of your app
• ✅ Can be tested independently
• ✅ Can be called by non-AI clients
• ✅ Easier to maintain and debug
• ✅ Can add authentication/caching

When to Use What

Use Just API Endpoint When:

• Building a regular web app
• Need data for your frontend
• Other services need to call it
• No AI involved

Use API + MCP Tool When:

• Want AI to access the data
• Building AI chat features
• Need intelligent data retrieval
• Want natural language interface

Summary: The Relationship

API Endpoint (data source)
    ↓
MCP Tool (AI access layer)
    ↓
OpenAI (intelligence)
    ↓
User (natural language)

Think of it this way:

• API Endpoint = What you have (data)
• MCP Tool = How AI accesses it (wrapper)
• Together = AI-powered application 🚀

---

📚 Key Takeaways

1. MCP = Tools for AI
   • You create tools (functions)
   • AI decides when to use them
   • AI can use multiple tools to answer questions
2. Three Main Parts:
   • API endpoints (your data)
   • MCP tools (how AI accesses data)
   • Chat endpoint (connects AI to tools)
3. Simple Pattern:User asks question → AI reads question → AI calls your MCP tools → Tools fetch data → AI generates answer → User sees response

---

🎓 Learning Resources

Official Documentation

• Next.js MCP Docs
• Vercel AI SDK
• OpenAI API

Example Projects

• This dashboard (you’re looking at it!)
• Vercel AI Examples

Video Tutorials

• Search YouTube for “Next.js MCP tutorial”
• Search for “Vercel AI SDK tutorial”

---

🎉 Congratulations!

You’ve built your first MCP server! You now understand:

✅ What MCP is and why it’s useful ✅ How to create API endpoints ✅ How to define MCP tools ✅ How to connect AI to your tools ✅ How to build a chat interface

Next Challenge: Try building a tool that:

• Reads data from a database
• Calls an external API
• Performs calculations
• Analyzes files

---

💡 Pro Tips

1. Start Simple
   • Begin with one tool
   • Add more as you learn
   • Test each tool individually
2. Good Tool Descriptions// ❌ Bad description: 'Gets data' // ✅ Good description: 'Get user profile information including name, email, and registration date'
3. Use Parameters// Let AI provide inputs parameters: z.object({ userId: z.number().describe('The ID of the user to fetch'), includeOrders: z.boolean().describe('Whether to include order history'), })
4. Error Handlingexecute: async ({ userId }) => { try { const user = await fetchUser(userId); return { success: true, user }; } catch (error) { return { success: false, error: 'User not found' }; } }

---

🤝 Need Help?

• Check the ARCHITECTURE.md for advanced concepts
• Read CONFIGURATION.md for setup options
• Review SETUP_GUIDE.md for detailed installation

Happy coding! 🚀