Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Build a local MCP server in JavaScript or TypeScript with the official TypeScript SDK: install @modelcontextprotocol/server, register a tool with a validated input schema, and connect over stdio. This walkthrough targets the SDK’s documented v2 stable line, which implements the 2026-07-28 MCP specification revision. The server provides capabilities to an MCP host or client; it does not provide the model or the host’s user interface.
What an MCP server does
An MCP server makes capabilities available to a client or host through the Model Context Protocol. A host connects to the server, discovers the capabilities it offers, and can use them according to its own interface and model behavior. The official TypeScript SDK overview names Claude Code, VS Code, Cursor, and custom applications as examples of hosts; check the current setup instructions for the specific host and version you intend to use. Official TypeScript SDK overview.
| Capability | What it provides | When to use it |
|---|---|---|
| Tools | Callable actions the client can ask the server to perform. | When the server needs to do something, such as look up information or run an operation. |
| Resources | Data that a client can read. | When the server exposes reference material or other data rather than an action. |
| Prompts | Reusable message templates. | When clients should be able to select prepared prompt content. |
A minimal server can start with one tool. You do not need to implement all three capability types. The official SDK overview describes tools, resources, and prompts as distinct server capabilities. SDK overview.
Recommended Free Tools
Choose the SDK version before you write code
This tutorial uses the v2 package, @modelcontextprotocol/server. The official SDK documentation marks v2 as the stable release line and says it implements protocol revision 2026-07-28. The older v1 documentation uses the monolithic package @modelcontextprotocol/sdk; these package names and API assumptions are not interchangeable. If you are upgrading a v1 project, follow the official migration guide rather than mixing v1 imports into a v2 example.
#1 Best Overall
The v2 SDK documentation lists Node.js, Bun, and Deno as supported runtimes, but the first-server setup used here is specifically for Node.js. Runtime requirements and API details can change; verify the current documentation before adopting a different runtime or upgrading the SDK. SDK overview and server documentation.
Set up a Node.js project
The official first-server walkthrough requires Node.js 20 or later and uses npm, TypeScript, Zod for input validation, and tsx to run TypeScript without a separate build step. It sets the package to ES modules because the SDK ships as ES modules. Official first-server walkthrough.
-
Check that Node.js 20 or later and npm are available:
Free tools Windows power users keep installed
One-click scans. No signup required.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.node --version npm --version -
Create a project and install the server dependencies:
mkdir mcp-js-server cd mcp-js-server npm init -y npm install @modelcontextprotocol/server zod npm install --save-dev typescript tsx -
Set the package to ES modules and add a development command to
package.json. Preserve any other fields npm has created:{ "type": "module", "scripts": { "dev": "tsx index.ts" } } -
Create
index.tsand add the server implementation below.Rank #2
Use the SDK package and API for one version line throughout the project. Installing a package successfully does not establish that a particular host supports your transport or setup; that is a separate compatibility check.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsRegister a tool and run the server over stdio
This example registers a small weather-alert lookup tool to show the pattern: a descriptive name, a description, a Zod input schema, and a handler returning protocol text content. It illustrates the official first-server walkthrough’s approach; the sample does not connect to a live weather service. In a real server, replace the example logic with an actual data source or operation.
import { McpServer } from "@modelcontextprotocol/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "weather-alerts",
version: "1.0.0",
});
server.registerTool(
"get_alerts",
{
title: "Get weather alerts",
description: "Return the example alert status for a US state code.",
inputSchema: {
state: z.string().length(2).describe("Two-letter US state code"),
},
},
async ({ state }) => ({
content: [
{
type: "text",
text: `Example only: no live alert lookup is configured for ${state.toUpperCase()}.`,
},
],
}),
);
const transport = new StdioServerTransport();
await server.connect(transport);The v2 API’s registerTool call takes a tool name, configuration including its input schema, and a callback. The SDK validates tool input against that schema before invoking the handler. A schema should describe the arguments your implementation can actually accept; validation is not a substitute for checking permissions or handling failures from an external service. See the v2 server documentation and the first-server walkthrough.
Run the server from the project directory:
npm run devIn stdio mode, the local host launches the server process and exchanges protocol messages over standard input and output. Keep stdout exclusively for protocol traffic. Do not add ordinary console.log debugging output: it can corrupt the stream. Send diagnostics to stderr instead, for example with console.error("Starting weather-alerts server"). The official walkthrough calls out this stdio requirement. First-server walkthrough.
Test the tool with MCP Inspector
MCP Inspector provides a local web interface for connecting to a server command and exercising its capabilities. Follow the official workflow: start Inspector with the command for this server, connect in the interface, choose the registered tool, enter valid arguments, and inspect the result. MCP Inspector documentation.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute-
From the project directory, launch Inspector with the command that runs your server:
Rank #3
npx @modelcontextprotocol/inspector tsx index.ts -
Open the local web UI reported by Inspector and connect to the server process.
-
Select
get_alerts, enter a two-characterstatevalue such asCA, and invoke the tool. -
Inspect the returned text. Try an invalid-length value as well to see input validation reject it before the handler runs.
Recommended: Fix Windows Errors and Clear Junk Files in Minutes - Free Scan →Recommended: Update Every Outdated Driver on Your PC in One Scan - Free →Recommended: PC Feels Slow? A Free Scan Shows What's Dragging Windows Down →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
If your installed Inspector version presents different controls or command options, use its current documentation. A successful Inspector call confirms the server can answer that test through the selected local transport; it does not by itself prove compatibility with every host.
Choose a transport for the way the server will run
| Transport | Best fit | What to plan for |
|---|---|---|
| stdio | A local integration where the host launches and owns the server process. | The host must know how to start the command; stdout must remain protocol-only. |
| Streamable HTTP | A server exposed as a remote endpoint. | Confirm the host supports the transport and plan deployment and access controls for the endpoint. |
| HTTP+SSE | Compatibility with clients that still require the older transport. | The v1 guide describes it as deprecated and retained for backward compatibility, not the default for new work. |
The SDK guidance distinguishes stdio for local process integrations from Streamable HTTP for remote use. The v1 server guide says HTTP+SSE is deprecated and retained for backward compatibility. Use the current v2 documentation for implementation details, and check the target host’s current transport support before choosing. SDK server guidance.
This walkthrough implements only local stdio. Remote deployment requires more than changing a transport: you must decide how the endpoint is hosted and protected, and ensure the client can reach it. The cited setup material does not provide a complete production security or deployment recipe, so use the current SDK and hosting documentation for those details rather than treating a local sample as production-ready.
Rank #4
Add resources or prompts only when they fit
Use resources to expose information clients can read, such as reference data. The v1 guidance distinguishes resources from tools: resources expose data and should not be used for heavy computation or side effects. Use tools for actions. Prompts are reusable message templates that clients can offer or select. A server does not need resources or prompts merely because the protocol supports them; add them when the client workflow benefits from those capabilities. SDK server guidance and SDK overview.
Troubleshoot common setup problems
-
Module or import errors: Confirm the project has
"type": "module", that the installed package is the v2@modelcontextprotocol/server, and that imports match the v2 documentation. Do not copy a v1@modelcontextprotocol/sdkimport into this project. -
Unsupported Node.js syntax or package behavior: Check
node --versionand use Node.js 20 or later for this documented walkthrough. Confirm that the version in use matches current SDK requirements. -
Inspector cannot connect or shows no tools: Check that the command points to the correct project and file, that the server starts without an exception, and that it reaches
server.connect. Use the Inspector interface to connect to the launched process before expecting the tool list. -
Protocol errors or garbled stdio traffic: Remove ordinary output from stdout. Keep logs and diagnostics on stderr so they cannot be mistaken for protocol messages.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
A tool call is rejected before your handler runs: Compare the supplied arguments with the Zod schema. In the example,
statemust be exactly two characters; adjust the input or schema to match the real tool contract. -
The server works locally but not in a host: Verify the host’s current launch configuration and transport support. Inspector testing does not verify every client’s setup or compatibility.
Or skip the browser setup
If your JavaScript MCP server needs website screenshots, ScreenshotNeo is a screenshot API and MCP server. A GET request with a URL returns an image or PDF. Its capture flow accepts cookie/consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status. The MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. See ScreenshotNeo and its API documentation.
Here is a complete cURL call; replace the example URL with the page you need and set your API key:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)Equivalent Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);For a quick evaluation, the Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. The response’s verdict and billing headers help distinguish a successful, billed capture from a failed or cached result.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does an MCP server include the AI model or chat interface?
No. It exposes capabilities to an MCP client or host; the model and user experience depend on that client.
Do I need to implement tools, resources, and prompts together?
No. They are separate capabilities. Start with the one your client workflow needs.
Can I use the v1 and v2 SDK package names interchangeably?
No. This tutorial targets the v2 package; consult the migration guide when moving a v1 project.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
