TypeScript MCP Server Boilerplate
This is a Vercel-deployed MCP server built on Next.js App Router, offering tools, prompts, and resources accessible via Streamable HTTP transport.
π οΈ Tools
greetβ Generate a greeting by providing a name and language (kooren)calculateβ Perform basic arithmetic (add,subtract,multiply,divide) on two numberstimeβ Get the current date and time for a specified timezone (default:Asia/Seoul)geocodeβ Look up latitude/longitude coordinates for a city name using Open-Meteoweatherβ Retrieve current weather conditions for given coordinates using Open-Meteogenerate-imageβ Generate images using HuggingFace's FLUX.1-schnell model (requiresHF_TOKENenv variable orx-hf-tokenrequest header)
π Prompts
code-reviewβ Generate a structured, senior-engineer-style code review from provided code
π¦ Resources
server-info(mcp://my-mcp-server/info) β Returns server metadata as JSON
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TypeScript MCP Server Boilerplatecalculate 5 + 3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
my-mcp-server (Vercel Β· Streamable HTTP)
Next.js App Router μ mcp-handler μμμ
λμνλ Vercel λ°°ν¬ν MCP μλ²μ
λλ€. κΈ°μ‘΄ StdioServerTransport κΈ°λ° λ‘컬
μλ²λ₯Ό Streamable HTTP νΈλμ€ν¬νΈλ‘ μ΄μ νμ¬ μμμ MCP ν΄λΌμ΄μΈνΈ(Cursor,
Claude Desktop, MCP Inspector λ±) μμ μ격μΌλ‘ νΈμΆν μ μμ΅λλ€.
μν€ν μ²
MCP Client (Cursor / Inspector)
β Streamable HTTP
β + x-hf-token header (μ ν)
βΌ
Next.js App Router (on Vercel)
app/api/[transport]/route.ts
β
βΌ
createMcpHandler ββΊ McpServer
ββ tools: greet / calculate / time / geocode / weather / generate-image
ββ prompts: code-review
ββ resources: server-info[transport] λμ μΈκ·Έλ¨ΌνΈλ₯Ό μ¬μ©ν΄ λ§€ μμ²λ§λ€ νΈλ€λ¬λ₯Ό μλ‘ λ§λ€κ³ , μμ² ν€λ
(x-hf-token) μ νκ²½λ³μ(HF_TOKEN) λ₯Ό ν΄λ‘μ λ‘ μΊ‘μ²ν΄ generate-image λꡬμ
μ λ¬ν©λλ€.
Related MCP server: TypeScript MCP Server Boilerplate
νλ‘μ νΈ κ΅¬μ‘°
.
βββ app/
β βββ api/
β β βββ [transport]/
β β βββ route.ts # MCP HTTP μλν¬μΈνΈ
β βββ layout.tsx
β βββ page.tsx # μλ΄μ© μ μ νμ΄μ§
βββ next.config.mjs
βββ next-env.d.ts
βββ package.json
βββ tsconfig.json
βββ .env.exampleλΉ λ₯Έ μμ
1. μμ‘΄μ± μ€μΉ
npm install2. νκ²½λ³μ μ€μ (μ ν)
generate-image λꡬλ₯Ό μ¬μ©ν κ³νμ΄λΌλ©΄ .env.example μ .env.local λ‘ λ³΅μ¬ν
λ€ HuggingFace ν ν°μ μ±μ λ£μ΅λλ€.
cp .env.example .env.local
# κ·Έλ¦¬κ³ HF_TOKEN=hf_xxx... λ‘ μμ νκ²½λ³μκ° μμ΄λ ν΄λΌμ΄μΈνΈκ° λ§€ μμ²λ§λ€
x-hf-tokenν€λλ₯Ό 보λ΄λ©΄ λμν©λλ€.
3. λ‘컬 μ€ν
npm run devκΈ°λ³Έ μλν¬μΈνΈ:
μλ΄ νμ΄μ§: http://localhost:3000
MCP Streamable HTTP: http://localhost:3000/api/mcp
4. MCP Inspector λ‘ κ²μ¦
npx @modelcontextprotocol/inspector@latestInspector UI μμ:
Transport: Streamable HTTP
URL:
http://localhost:3000/api/mcp(μ ν) Custom Headers μ
x-hf-token: hf_xxx...μΆκ°Connect β List Tools β κ° λꡬ νΈμΆ ν μ€νΈ
ν΄λΌμ΄μΈνΈ μ°κ²°
Cursor (./.cursor/mcp.json)
{
"mcpServers": {
"my-mcp-server": {
"url": "https://<your-app>.vercel.app/api/mcp",
"headers": {
"x-hf-token": "hf_xxx..."
}
}
}
}url λ§ μμΌλ©΄ 5κ° λꡬ(greet/calculate/time/geocode/weather)λ μ μ
λμν©λλ€. generate-image λ₯Ό μ¬μ©νλ €λ©΄ headers.x-hf-token λλ μλ²μΈ‘
HF_TOKEN νκ²½λ³μ μ€ νλκ° λ°λμ νμν©λλ€.
Streamable HTTP λ―Έμ§μ ν΄λΌμ΄μΈνΈ (mcp-remote λΈλ¦Ώμ§)
{
"mcpServers": {
"my-mcp-server": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://<your-app>.vercel.app/api/mcp",
"--header",
"x-hf-token:hf_xxx..."
]
}
}
}Vercel λ°°ν¬
λ°©λ² 1: Vercel CLI
npm i -g vercel
vercelλ°©λ² 2: GitHub μ°λ
GitHub μ μ₯μμ νΈμ
https://vercel.com/new μμ μ μ₯μ μ ν
Framework Preset: Next.js (μλ κ°μ§)
Environment Variables μμ (μ ν)
HF_TOKENμΆκ°Deploy
λ°°ν¬κ° μλ£λλ©΄ https://<your-app>.vercel.app/api/mcp κ° MCP μλν¬μΈνΈμ
λλ€.
λ±λ‘λ λꡬ
μ΄λ¦ | μ€λͺ |
| μ΄λ¦κ³Ό μΈμ΄(ko/en)λ‘ μΈμ¬λ§ μμ± |
| λ μ«μ μ¬μΉμ°μ° (add/subtract/multiply/divide) |
| νμμ‘΄λ³ νμ¬ μκ° |
| Open-Meteo λ‘ λμλͺ β μκ²½λ μ‘°ν |
| Open-Meteo λ‘ μκ²½λ β νμ¬ λ μ¨ μ‘°ν |
| HuggingFace FLUX.1-schnell μ΄λ―Έμ§ μμ± ( |
ν둬ννΈ / 리μμ€
ν둬ννΈ
code-review: μ½λλ₯Ό μ λ ₯λ°μ μλμ΄ μμ§λμ΄ κ΄μ μ 체κ³μ 리뷰 λ©μμ§ μμ±λ¦¬μμ€
server-info(mcp://my-mcp-server/info): μλ² λ©νλ°μ΄ν°(JSON)
HF_TOKEN μ²λ¦¬ μ μ±
x-hf-token ν€λ ββ(μμΌλ©΄ μ¬μ©)βββΊ HuggingFace Inference
β (μμ)
βΌ
HF_TOKEN νκ²½λ³μ ββ(μμΌλ©΄ μ¬μ©)βββΊ HuggingFace Inference
β (μμ)
βΌ
generate-image λκ΅¬κ° λͺ
νν μλ¬ λ©μμ§ λ°νν€λκ° μ°μ μ΄λ―λ‘ λμΌ λ°°ν¬ μΈμ€ν΄μ€λ₯Ό μ¬λ¬ μ¬μ©μκ° κ°μμ ν ν°μΌλ‘ μ¬μ©ν μ μμ΅λλ€.
μ€ν¬λ¦½νΈ
npm run dev: λ‘컬 κ°λ° μλ²npm run build: νλ‘λμ λΉλnpm run start: λΉλ κ²°κ³Ό μ€νnpm run lint: Next.js lint
μ°Έκ³ μλ£
λΌμ΄μ μ€
MIT
Available Tools
6 toolscalculateA
λ μ«μμ λν΄ μ¬μΉμ°μ°(+, -, *, /)μ μνν©λλ€.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | 첫 λ²μ§Έ μ«μ | |
| b | Yes | λ λ²μ§Έ μ«μ | |
| operation | Yes | μ°μ° μ’ λ₯: add(+), subtract(-), multiply(*), divide(/) |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes | κ³μ° κ²°κ³Ό |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose error handling (e.g., division by zero), precision, or side effects. A simple statement of operations is insufficient for a safe tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core functionality without any superfluous words. It is well-front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool, full schema coverage, and presence of an output schema, the description is largely complete. However, it could mention division-by-zero handling or result types for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds overall context but does not provide additional meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs four arithmetic operations on two numbers, using specific verbs and resources. It distinguishes itself from sibling tools like generate-image, geocode, etc., which serve entirely different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for arithmetic computations but provides no explicit guidance on when to use it versus alternatives or when not to use it. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate-imageA
HuggingFace FLUX.1-schnell λͺ¨λΈλ‘ μ΄λ―Έμ§λ₯Ό μμ±ν©λλ€. HF_TOKEN νκ²½λ³μκ° νμν©λλ€.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | μ΄λ―Έμ§ μμ± ν둬ννΈ | |
| num_inference_steps | No | μΆλ‘ μ€ν μ (1~10, κΈ°λ³Έκ° 4) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses the model and env requirement, but omits details like error behavior if token is missing, rate limits, or output format. The added context is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with key information (model and env requirement). No fluff, but could potentially add more value without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count and full schema coverage, the description is fairly complete but lacks information about output (no output schema) and error handling. It adequately covers prerequisites but falls short on behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (prompt, num_inference_steps). The description adds no extra semantic information beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states that the tool generates an image using the HuggingFace FLUX.1-schnell model, clearly identifying the verb (generate) and resource (image/model). Sibling tools are unrelated (calculate, geocode, etc.), so no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the required HF_TOKEN environment variable but provides no guidance on when to use this tool versus alternatives, nor when not to use it. Since siblings are not image-generation tools, usage is implicitly clear but lacks explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
geocodeA
λμ μ΄λ¦μΌλ‘ μλΒ·κ²½λ μ’νλ₯Ό μ‘°νν©λλ€.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | κ²μν λμλͺ (μ: μμΈ, Tokyo) | |
| language | No | κ²°κ³Ό μΈμ΄ (κΈ°λ³Έκ°: ko) | ko |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not mention behaviors such as error handling, rate limits, or authentication. It only states the basic function, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that delivers the core function. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the return format is likely documented, but the description lacks information on error scenarios or limitations. It is adequate for a simple lookup but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the schema's parameter descriptions without adding new details. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve) and resource (latitude/longitude coordinates) by city name. It is distinct from sibling tools like weather or calculate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The purpose is clear, but there is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
greetA
μ΄λ¦κ³Ό μΈμ΄λ₯Ό μ λ ₯νλ©΄ μΈμ¬λ§μ λ°νν©λλ€.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | μΈμ¬ν μ¬λμ μ΄λ¦ | |
| language | No | μΈμ¬ μΈμ΄ (κΈ°λ³Έκ°: en) | en |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes | μΈμ¬λ§ |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the core behavior (returns a greeting) but does not disclose details like output formatting, error handling, or whether there are side effects. For a simple tool, this is acceptable but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that covers the tool's purpose without any extraneous words. It is front-loaded with the core action and efficiently communicates the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with a complete input schema and an output schema, the description is sufficient. It explains the function clearly, and the remaining details are covered by the structured fields, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for both parameters (name, language) with enums and defaults. The description merely restates that they are inputs and does not add additional semantic context beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a greeting based on a name and language, using a specific verb (λ°νν©λλ€) and a clear resource (greeting). This is distinct from sibling tools like geocode or get-weather, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a greeting is needed, but it does not explicitly state when to use this tool versus alternatives. Since sibling tools are unrelated, no exclusions are necessary, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
timeA
νμ¬ λ μ§μ μκ°μ λ°νν©λλ€.
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | νμμ‘΄ (κΈ°λ³Έκ°: Asia/Seoul, μ: America/New_York, UTC) | Asia/Seoul |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes | νμ¬ μκ° μ 보 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral details. It only states the basic return value without specifying format, timezone handling beyond parameter, or any side effects. This leaves important behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose. Every word is necessary, and there is no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the existence of an output schema, the description is minimally adequate. However, it lacks details about return format or example usage, which would enhance completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter with a description of timezone. The tool description does not add further semantic value beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current date and time, using a specific verb and resource. It is easily distinguishable from sibling tools like calculate or weather, which cover different domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use or avoid this tool. However, the purpose is straightforward and implied for any situation needing the current date/time, so it is adequate but lacks explicit guidance or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
weatherB
μλΒ·κ²½λ μ’νλ‘ νμ¬ λ μ¨λ₯Ό μ‘°νν©λλ€.
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | Yes | μλ | |
| longitude | Yes | κ²½λ |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states it queries current weather without detailing behavior like error handling, rate limits, or data format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear structure. Efficiently conveys core functionality without extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, description need not detail returns. However, lacks edge cases or usage context for a simple weather query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds no additional meaning beyond the schema's 'μλ' and 'κ²½λ'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (μ‘°ν = query) and resource (λ μ¨ = weather) with specific input coordinates. Distinct from siblings like geocode and calculate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool or alternatives. Does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v1.0.0- First observed
calculate - First observed
generate-image - First observed
geocode - First observed
greet - First observed
time - First observed
weather
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose (arithmetic, image generation, geocoding, greeting, time, weather), with no overlap or ambiguity in their intended use.
Most tool names are single-word verbs (calculate, geocode, greet, time, weather), with one hyphenated compound (generate-image). This is mostly consistent but the hyphenated name is a minor deviation.
With 6 tools, the count is reasonable for a boilerplate example server. It is neither too sparse nor overly heavy for illustrating various capabilities.
As a boilerplate, the tool set does not target a specific domain, so completeness is inherently neutral. The tools cover basic utility examples but lack any overarching purpose or desired workflow.
Maintenance
Related MCP Connectors
A simple Typescript MCP server built using the official MCP Typescript SDK and smithery/cli. Thisβ¦
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automatiβ¦
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA boilerplate project for quickly developing MCP servers with TypeScript, featuring example tools (calculator, greeting, time) and resources with Zod schema validation.-
- FlicenseNot gradedqualityDmaintenanceA boilerplate project for quickly developing MCP servers using TypeScript SDK, featuring example tools (calculator, greeting) and resources with Zod schema validation.-
- FlicenseNot gradedqualityDmaintenanceA boilerplate project for quickly developing MCP servers using TypeScript SDK, with example implementations of calculator and greeting tools, plus resource handling capabilities.-
- FlicenseNot gradedqualityDmaintenanceA boilerplate project for quickly developing Model Context Protocol (MCP) servers using TypeScript, with example tools (calculator, greet) and resources (server info) pre-implemented.31-