Mini Project - Person App - Self-Paced Exercise 5 - Extend to MCP Servers (Agentic AI)

Now, let's make your Person App Agentic. This means, we expose your CRUD app directly into LLMs. We do this via a protocol called MCP.

You can learn more about building and deploying your own agent here using the Roll Dice example: https://aiagents.ausbizconsulting.com.au/builders-toolkit

In this exercise, you will need

• Visual Studio Code Insider Edition
• Github Copilot Pro (Education or Paid Plan, eg $10/month)
• Claude Sonnet 4.5 (minimum)
• Github MCP Server installed in your Visual Studio Code Insider

Step 1:

Study the Roll Dice MCP Server Repository: https://github.com/gocallum/rolldice-mcpserver

Key points to note

• Pay attention to the pre-build MCP library mcp-handler by Vercel https://github.com/vercel/mcp-handler
• Important to note the folder: app/api/[transport]

1// app/api/[transport]/route.ts
2import { createMcpHandler } from "mcp-handler";
3import { rollDice, rollDiceTool } from "@/lib/dice";
4
5const handler = createMcpHandler(
6  (server) => {
7    server.tool(
8      rollDiceTool.name,
9      rollDiceTool.description,
10      rollDiceTool.schema,
11      async ({ sides }) => {
12        // Use the shared dice rolling logic
13        const result = rollDice(sides);
14        return {
15          content: [result],
16        };
17      }
18    );
19  },
20  {
21    // Optional server options
22  },
23  {
24    // No Redis config - disable Redis requirement
25    basePath: "/api", // this needs to match where the [transport] is located.
26    maxDuration: 60,
27    verboseLogs: true,
28  }
29);
30export { handler as GET, handler as POST };

Big picture: what this file does

• This is an App Router API route at /api/[transport].
• It uses createMcpHandler from mcp-handler to turn this route into an MCP server endpoint.
• That MCP server exposes a single tool called rollDice, which the AI client (ChatGPT, Claude, etc.) can call via MCP.

So: this file is the HTTP/SSE bridge between your MCP client and your “dice rolling” business logic.

The core MCP wiring

1. createMcpHandler(...)

1const handler = createMcpHandler(
2  (server) => {
3    // register tools here
4  },
5  {
6    // Optional server options
7  },
8  {
9    basePath: "/api",
10    maxDuration: 60,
11    verboseLogs: true,
12  }
13);

createMcpHandler is doing a few things for you:

1. It creates an MCP server instance and passes it into your callback (server) => { ... }.
2. Inside the callback, you register MCP tools using server.tool(...).
3. It wraps everything in a Next.js-compatible handler that can respond to both GET and POST.
4. It honors transport options like basePath, maxDuration, and verboseLogs.

You then export that handler as both HTTP methods:

1export { handler as GET, handler as POST };

So Next.js sees:

• GET /api/sse or GET /api/http (depending on transport path param) → handled by your MCP handler.
• POST /api/[transport] → same handler.

The [transport] segment is used by mcp-handler to support different transports (e.g. SSE vs HTTP) under the same API structure.

Step 2:

You can test this out with rolldice server hosted on the Ausbiz Consulting website.

Change the URL to your own hosted, either locally, or hosted on Vercel. This will help you get familiar with the URL pattern.

1{
2  "servers": {
3    "rolldice": {
4      "type": "http",
5      "url": "https://rolldice.ausbizconsulting.com.au/api/mcp"
6    }
7  }
8}

2. Registering the MCP tool

This is the real “MCP heart”:

1(server) => {
2  server.tool(
3    rollDiceTool.name,
4    rollDiceTool.description,
5    rollDiceTool.schema,
6    async ({ sides }) => {
7      const result = rollDice(sides);
8      return {
9        content: [result],
10      };
11    }
12  );
13}

Think of server.tool as:

“Register a tool with this MCP server so that the client can discover and call it.”

The parameters:

1. rollDiceTool.name
   – The tool name exposed to MCP clients (like "rollDice").
   – The client (ChatGPT/Claude) will see this name when listing tools.
2. rollDiceTool.description
   – Human-readable description (e.g. "Rolls a dice with N sides").
   – Shows up in the MCP client’s “tool description” so the model knows when to call it.
3. rollDiceTool.schema
   – JSON schema for tool arguments.
   – Something like:

1{
2  type: "object",
3  properties: {
4    sides: { type: "number", minimum: 1 }
5  },
6  required: ["sides"]
7}

1. – The MCP layer uses this to:
2. • Validate arguments.
   • Tell the LLM what parameters are allowed and required.
2. async ({ sides }) => { ... }
   – The implementation of the tool.
   – When the model calls this tool via MCP with arguments { "sides": 6 }, this function runs with sides = 6.

Inside the implementation:

1const result = rollDice(sides);
2return {
3  content: [result],
4};

• rollDice(sides) is your shared business logic (from @/lib/dice).
• The return shape { content: [result] } is what mcp-handler expects for a response:
• • content is an array of content blocks (often strings or objects) that the MCP client will pass back to the LLM as the tool result.
  • In a more complex tool you might return structured objects or multiple content blocks; here it’s a simple value (e.g. "You rolled a 4 on a 6-sided dice").

3. Options passed to createMcpHandler

You’ve got two options objects after the callback.

a) Server options (second argument)

1{
2  // Optional server options
3}

You’re not setting anything here, but this is typically where you’d configure things like:

• Server name / version metadata.
• Any global behavior for tools.

Since it’s empty, default behavior is used.

b) Transport/runtime options (third argument)

1{
2  // No Redis config - disable Redis requirement
3  basePath: "/api", // this needs to match where the [transport] is located.
4  maxDuration: 60,
5  verboseLogs: true,
6}

These are more about how the handler runs inside Next.js:

• basePath: "/api"
• • Tells mcp-handler that your MCP route lives under /api.
  • Combined with [transport], your MCP endpoints look like /api/sse, /api/http, etc.
  • This must match the directory structure: app/api/[transport]/route.ts.
• maxDuration: 60
• • Maximum allowed execution time in seconds for a request / tool call.
  • Helps prevent very long-running tool executions from hanging.
• verboseLogs: true
• • Enables more detailed logging.
  • Super useful when debugging:
  • • handshakes
    • tool registration
    • tool invocations
    • errors from your implementations
• “No Redis config – disable Redis requirement”
• • Some mcp-handler setups may use Redis for things like session/state.
  • By omitting that config, you’re telling it to run in a simpler, stateless mode suitable for demos and simple tools.

4. How this interacts with your MCP client

From the perspective of an MCP client (e.g. a ChatGPT or Claude MCP config):

1. The client connects to /api/sse (or /api/http, etc., depending on transport).
2. The createMcpHandler code:
3. • Spins up the MCP server.
   • Registers your rollDice tool.
   • Handles the incoming MCP protocol messages.
3. When the LLM decides “I should roll a dice”, it calls the rollDice tool via MCP.
4. mcp-handler:
5. • Validates arguments against rollDiceTool.schema.
   • Calls your async ({ sides }) => { ... } implementation.
   • Sends { content: [result] } back to the MCP client.

Step 3

Create a file called mcp-prd.md in the root folder, or in a sub-folder eg /docs

1Use the Github MCP server to learn the code from https://github.com/gocallum/rolldice-mcpserver/
2
3Note that this uses mcp-handler package. 
4
5Use the same pattern in the rolldice mcp server to create mcp-handler that leverages my existing server actions that perform crud operations. 
6
7Once you are done, update my .vscode/mcp.json to include my mcp-server 
8
9{
10  "servers": {
11    "person-app-mcp": {
12      "type": "http",
13      "url": "http://localhost:3000/api/mcp"
14    }
15  }
16}
17
18And then help me to test.

Step 4

Now get Claude Sonnet 4.5 or higher to generate the code and test.