Building Custom MCP Servers with Next.js and mcp-handler

1
┌─────────────┐                         ┌─────────────┐
2
│   VS Code   │  ──"list tools"──────▶  │ MCP Server  │
3
│             │  ◀─tool definitions───  │             │
4
└─────────────┘                         └─────────────┘
5
       │
6
       ▼
7
┌─────────────┐                         ┌─────────────┐
8
│   Claude    │  ──"npm_package zod"─▶  │ MCP Server  │
9
│             │  ◀─{version, weekly..}  │             │
10
└─────────────┘                         └─────────────┘
11
       │
12
       ▼
13
  "zod is at v4.3.6 with 86M weekly downloads"

1
{
2
  "result": {
3
    "content": [{
4
      "type": "text",
5
      "text": {
6
        "name": "zod",
7
        "version": "4.3.6",
8
        "weeklyDownloads": "86,259,569",
9
        "repository": "https://github.com/colinhacks/zod"
10
      }
11
    }]
12
  }
13
}

1
server.tool(
2
  "github_repo",
3
  "Get GitHub repo info: stars, forks, issues, last update.",
4
  {
5
    owner: z.string().describe("Repo owner, e.g. 'facebook'"),
6
    repo: z.string().describe("Repo name, e.g. 'react'"),
7
  },
8
  async ({ owner, repo }) => {
9
    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
10
      headers: { "Accept": "application/vnd.github.v3+json" },
11
    });
12

13
    if (!res.ok) {
14
      return {
15
        content: [{ type: "text", text: `Repo "${owner}/${repo}" not found.` }],
16
        isError: true,
17
      };
18
    }
19

20
    const data = await res.json();
21
    return {
22
      content: [{
23
        type: "text",
24
        text: JSON.stringify({
25
          name: data.full_name,
26
          description: data.description,
27
          stars: data.stargazers_count.toLocaleString(),
28
          forks: data.forks_count.toLocaleString(),
29
          openIssues: data.open_issues_count,
30
          lastPush: data.pushed_at,
31
        }, null, 2),
32
      }],
33
    };
34
  }
35
);

1
server.tool(
2
  "check_site",
3
  "Check if a site is up. Returns status and response time.",
4
  {
5
    url: z.string().url().describe("URL to check"),
6
  },
7
  async ({ url }) => {
8
    const start = Date.now();
9
    try {
10
      const res = await fetch(url, {
11
        method: "HEAD",
12
        signal: AbortSignal.timeout(10000),
13
      });
14
      return {
15
        content: [{
16
          type: "text",
17
          text: JSON.stringify({
18
            url,
19
            status: res.ok ? "up" : "down",
20
            httpStatus: res.status,
21
            latencyMs: Date.now() - start,
22
          }, null, 2),
23
        }],
24
      };
25
    } catch (err) {
26
      return {
27
        content: [{
28
          type: "text",
29
          text: JSON.stringify({
30
            url,
31
            status: "unreachable",
32
            error: (err as Error).message,
33
          }, null, 2),
34
        }],
35
        isError: true,
36
      };
37
    }
38
  }
39
);