
The Model Context Protocol lets AI assistants such as Claude, Cursor and many others connect to external tools and data through a standard interface. Instead of building separate integrations for every AI application, you build one MCP server and any compatible client can use it. In this model context protocol tutorial, you will build an MCP server in TypeScript from scratch, add custom tools and resources, test it with the MCP Inspector and connect it to Claude Desktop.
First, a quick overview of what an MCP server provides.
What an MCP Server Provides
An MCP server can expose three kinds of capabilities:
- Tools: functions the AI can call, such as searching a database, creating a ticket or fetching weather data.
- Resources: read-only data the client can load, such as files or records.
- Prompts: reusable prompt templates the user can select.
Clients discover these capabilities automatically when they connect. The server communicates over standard input and output for local use, or over HTTP for remote use.
What You Need
- Node.js 20 or later.
- Basic TypeScript knowledge.
- Claude Desktop or another MCP client for final testing.
- A code editor such as VS Code.
Step 1: Create the Project
Open a terminal and create a folder with mkdir notes-mcp-server, then move into it with cd notes-mcp-server. Run npm init -y to create a package file.
Install the MCP TypeScript SDK and zod by running npm install @modelcontextprotocol/sdk zod. Install development dependencies with npm install --save-dev typescript @types/node.
Create a TypeScript configuration with npx tsc --init, then set the module and module resolution options to Node16 and the output directory to build. In your package file, set type to module and add a build script that runs tsc.
Visual description: your folder now contains a package file, a tsconfig file and a node_modules folder. Create a src folder with an index.ts file inside it.
Step 2: Create the Server
In src/index.ts, import McpServer from the SDK's server module and StdioServerTransport from the stdio module. Create a new server instance with a name, such as notes-server, and a version number.
For this tutorial, the server will manage simple notes stored in memory. Create an array to hold notes, where each note has an id, a title and content.
Step 3: Add Your First Tool
Use the server's registerTool method to define a tool named add_note. Provide:
- A title and description: Add a new note with a title and content. Clear descriptions matter because the AI reads them to decide when to use the tool.
- An input schema using zod, with title and content as strings, each with a short description.
- A handler function that creates the note, adds it to the array and returns a text result confirming the note was saved with its id.
Add a second tool named search_notes that accepts a query string and returns notes whose title or content contains the query. Return results as readable text, or a message saying no notes were found.
These custom mcp tools demonstrate the core pattern: schema, description and handler.
Step 4: Add a Resource
Resources expose data the client can read. Register a resource named all-notes with a URI such as notes://all. Its handler returns the full list of notes as text or JSON. Clients may display resources for users to attach to conversations.
Step 5: Connect the Transport
At the bottom of the file, create a StdioServerTransport and connect the server to it inside an async main function. Add error handling that logs errors to standard error and exits.
Important: never write logs to standard output in a stdio server, because standard output carries protocol messages. Use console.error for logging.
Step 6: Build the Server
Run npm run build. TypeScript compiles your code into the build folder. Fix any type errors reported.
Step 7: Test With the MCP Inspector
The mcp inspector is an interactive tool for testing servers without an AI client. Run npx @modelcontextprotocol/inspector node build/index.js.
Visual description: a browser window opens showing a connection panel on the left and tabs for Tools, Resources and Prompts. Click Connect, then open the Tools tab to see add_note and search_notes listed with their descriptions and input fields.
Call add_note with a sample title and content, then call search_notes with a word from the note. Confirm the results appear correctly. Check the Resources tab to read notes://all.
Testing in the Inspector first saves time, because errors are easier to see than inside an AI client.
Step 8: Connect to Claude Desktop
To connect your server to claude desktop mcp settings, open Claude Desktop's settings and find the developer section, which lets you edit the configuration file. Add an entry under mcpServers with a name for your server, the command node, and an args array containing the absolute path to build/index.js.
Restart Claude Desktop. Visual description: a tools indicator appears in the chat input area; clicking it shows your notes server and its tools.
Ask Claude to save a note about tomorrow's meeting, then ask it to find notes about meetings. Claude will request permission to use your tools and then call them.
You can connect the same server to Claude Code using the claude mcp add command, or to other MCP clients using their configuration.
Step 9: Improve Your Server
- Persist notes to a file or database instead of memory.
- Add input validation and helpful error messages returned as tool results.
- Add tool annotations indicating whether tools are read-only or destructive, so clients can handle approvals appropriately.
- Write concise, specific tool descriptions to help the AI choose correctly.
- Return focused results rather than large data dumps, to conserve the AI's context.
Troubleshooting Common Issues
Server not appearing in Claude Desktop: check that the configuration file is valid JSON and uses an absolute path, then fully restart the app.
Connection closes immediately: look for errors in Claude Desktop's MCP logs; often the build is missing or the path is wrong.
Strange protocol errors: ensure nothing writes to standard output, including stray console.log statements.
Tool not used by the AI: improve the tool description and name to clearly explain its purpose.
Module errors: confirm the package type is module and the TypeScript module settings match.
Frequently Asked Questions
Can my MCP server call external APIs? Yes. Tool handlers can call any API or database. Store credentials in environment variables passed through the client configuration.
Can I deploy the server remotely? Yes, using the Streamable HTTP transport with authentication, which allows web-based clients and teams to share one server.
Conclusion
You have learned to build mcp server typescript projects using the official mcp typescript sdk: creating a server, registering tools and resources, connecting a stdio transport, testing with the MCP Inspector and connecting to Claude Desktop.
Key takeaways: write clear tool descriptions, validate inputs with zod, never log to standard output, test in the Inspector first and keep results focused. Next, connect your server to a real data source your team uses daily and share it through project configuration.