How to Build an MCP Server with the Official TypeScript and Python SDKs

How do you create an MCP server?
To create an MCP server with Model Context Protocol (MCP), install the official software development kit (SDK), register a tool, serve it over standard input and output (stdio), test it with MCP Inspector, then add it to a host’s configuration file.
The server is a program that offers actions to an AI application; a tool is one such action. The Inspector is a testing app, and a host is the AI application that runs the server.
Model Context Protocol connects an AI application to external actions and data. Say you want an assistant to find a repository’s open issues: first make the issue data available, then build a server that offers an action to read it, and finally connect that server to the assistant. For the basics, see what MCP is and why it exists.
The host is the AI application where you ask for open issues. Its MCP client communicates with the server and can discover and call the issue-listing tool. The server reads the local issue file and offers list_open_issues. The SDK supplies the code for speaking MCP. Stdio sends messages through the process’s standard input and output streams.
What you need
Choose TypeScript or Python; you don’t need both. For either path, use a terminal. The Inspector needs a supported Node.js version, including for Python; the supported versions are listed in the TypeScript setup below. The Python path needs Python 3.10 or newer.
Step 1: Set up a project and install the SDK
Create an empty project directory and run the commands for your chosen language inside it. The TypeScript commands create a Node project, mark its files as modules, and install the server SDK, the schema library Zod and the TypeScript runner tsx; exact versions keep future installs consistent.
# Inspector Node.js versions: ^22.23.4 || ^24.22.1 || >=26.12.1
npm init -y
npm pkg set type=module
npm install --save-exact @modelcontextprotocol/server@2.4.0 zod@4.6.7 tsx@4.23.15
For Python, create and activate an isolated environment, then install the SDK and its command-line tools:
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]==2.3.0"
Create issues.json in the project directory. The closed entry makes the filter visible when you test it.
[
{"number": 1, "title": "Fix login", "state": "open"},
{"number": 2, "title": "Update docs", "state": "closed"},
{"number": 3, "title": "Add tests", "state": "open"}
]
Step 2: Write the server and register its tool
Registering a tool gives the SDK its name, description, input schema and implementation. An input schema describes the arguments a tool accepts; here it accepts none. The server reads issues.json beside the server file, so the host’s working directory does not change which file it reads.
MCP TypeScript SDK
Save this as server.ts in the same directory as issues.json:
import { readFile } from 'node:fs/promises';
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
function createServer(): McpServer {
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'list_open_issues',
{ description: 'List open issues from the local file', inputSchema: z.object({}) },
async () => {
const issues = JSON.parse(await readFile(new URL('./issues.json', import.meta.url), 'utf8'));
return { content: [{ type: 'text', text: JSON.stringify(issues.filter((issue: { state: string }) => issue.state === 'open')) }] };
}
);
return server;
}
void serveStdio(createServer);
serveStdio calls createServer to make a fresh server when needed and negotiates the message rules with the client.
MCP Python SDK
Save this as server.py beside issues.json:
import json
from pathlib import Path
from mcp.server import MCPServer
mcp = MCPServer("issues")
@mcp.tool()
def list_open_issues() -> str:
"""List open issues from the local file."""
issues = json.loads(Path(__file__).with_name("issues.json").read_text())
return json.dumps([issue for issue in issues if issue["state"] == "open"])
if __name__ == "__main__":
mcp.run()
The decorator registers the function as a tool; mcp.run() serves it over stdio. Both versions return the open entries as text containing JSON, a format for structured data.
Step 3: Test discovery and the result with MCP Inspector
MCP Inspector can launch the server and act as a client. MCP has older and newer message rules (the current version is 2026-07-28), and a client may speak either, so the Inspector’s modern and legacy options test both to show whether your server works with each. Run these commands from the project directory. For TypeScript:
npx @modelcontextprotocol/inspector@2.15.0 --cli npx tsx server.ts --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector@2.15.0 --cli npx tsx server.ts --protocol-era legacy --method tools/list
npx @modelcontextprotocol/inspector@2.15.0 --cli npx tsx server.ts --method tools/call --tool-name list_open_issues
For Python, with the environment still active:
npx @modelcontextprotocol/inspector@2.15.0 --cli .venv/bin/mcp run server.py --method tools/list
npx @modelcontextprotocol/inspector@2.15.0 --cli .venv/bin/mcp run server.py --method tools/call --tool-name list_open_issues
These Python commands use the Inspector’s default; to test both message rules, run the tools/list line twice more with --protocol-era modern and --protocol-era legacy, as in the TypeScript lines.
The list should include list_open_issues. The call should show the open entries, “Fix login” and “Add tests”, inside the result like this (shortened); “Update docs” should be absent:
"content": [{"type":"text","text":"[{\"number\":1,\"title\":\"Fix login\",…},{\"number\":3,\"title\":\"Add tests\",…}]"}]
If the tool is missing, check the file name and registration. If the call fails, check that issues.json is beside the server file. For how the client and server exchange messages, read the MCP architecture guide.
If you only needed to build and test the server, you can stop here. Continue to use it in an assistant or consider a remote connection.
Step 4: Connect the server to a host
A configuration file tells a host which command starts the server. For Cursor, an AI coding editor, create .cursor/mcp.json in your project. This example uses the Python server; replace both paths with the absolute paths to your project. On Windows, use the Python executable inside the environment’s Scripts directory.
{
"mcpServers": {
"issues": {
"command": "/absolute/path/to/project/.venv/bin/python",
"args": ["/absolute/path/to/project/server.py"]
}
}
}
For TypeScript, set command to npx and args to ["tsx", "/absolute/path/to/project/server.ts"]. Open the project in Cursor and check Available Tools for list_open_issues, then ask the assistant to list open issues and approve the tool call when Cursor asks by default.
The tool should return the same open entries as the Inspector. This guide does not show a tested Cursor connection, so use the Inspector result to separate a server problem from a host configuration problem.
For a remote server, Streamable HTTP carries MCP messages over HTTP. The Python SDK can start this same server locally with the command below; its default address is local to your machine. A remote deployment must validate the Origin header and should require authentication; consult the MCP transport specification before exposing it.
.venv/bin/mcp run server.py --transport streamable-http
Step 5: Keep the local server safe
A local server runs as a process with your account’s access; MCP does not sandbox it. Validate every tool input, even when you add arguments later. Give the process only the file access it needs and no network access where possible.
On stdio, write logs to stderr, the error stream, not stdout, which carries MCP messages. Pin SDK versions and update them after checking advisories: a pin prevents surprise updates but does not guarantee future safety. See the MCP local server security guidance and tool requirements.
Mistakes to avoid
- Importing
FastMCPfrommcp.server.fastmcp: that path fails with the Python SDKmcp2.3.0. ImportMCPServerfrommcp.serverinstead. - Using the older
@modelcontextprotocol/sdkexample for a current client: that package is the maintenance line and does not support the current revision. That README’s manualStdioServerTransportconnection serves only clients that use the older message rules, according to the MCP build-a-server guide. Use the server package andserveStdio, then test with both themodernandlegacyoptions from Step 3. - Printing logs to stdout on stdio: extra output can corrupt the messages. Send logs to stderr.
- Using
.vscode/mcp.jsonwithserversfor a new VS Code Copilot setup: that is VS Code’s older editor-managed configuration, which is deprecated. Use a workspace-root.mcp.jsonwithmcpServersfor a new Copilot configuration; check the host’s own instructions before copying settings between editors.
Ask an AI coding assistant to add a tool
Paste this into your coding assistant after the existing server works:
Add a second tool to this MCP server that looks up an issue by its number in issues.json. Validate the input, use no network, and log only to stderr. Keep serveStdio for the TypeScript server. Preserve the existing list_open_issues tool and show how to test the new tool with MCP Inspector.
Cheat sheet
The article on one page: open it full size, save it or share it.

AI-assisted content, human-reviewed. Images AI-generated. Editorial Standards · Our Editors