MCP Server Starter

The Model Context Protocol (MCP) is a specialized framework designed to streamline the process of enabling AI agents to interact with a wide array of tools. This starter template helps you quickly build a Model Context Protocol (MCP) server using TypeScript. It provides a robust foundation that you can easily extend to create advanced MCP tools and seamlessly integrate them with various AI platforms.

- MCP Servers: These servers act as bridges, exposing APIs, databases, and code libraries to external AI hosts. By implementing an MCP server in TypeScript, developers can share data sources or computational logic in a standardized way using JSON-RPC 2.0.
- MCP Clients: These are the consumer-facing side of MCP, communicating with servers to query data or perform actions. MCP clients use TypeScript SDKs, ensuring type-safe interactions and uniform approach to tool usage.
- MCP Hosts: Systems such as Claude, Cursor, Windsurf, Cline, and other TypeScript-based platforms coordinate requests between servers and clients, ensuring seamless data flow. A single MCP server can thus be accessed by multiple AI hosts without custom integrations.

The MCP TypeScript SDK provides core classes for building servers:

import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server({ name: "mcp-server-starter", version: "1.0.0", capabilities: { tools: {}, // Enable tools capability resources: {}, // Enable resource access prompts: {}, // Enable prompt handling streaming: true // Enable streaming responses } }); // Connect transport const transport = new StdioServerTransport(); await server.connect(transport);

By using MCP, developers no longer need complex custom code to integrate new tools or services. Instead, they build an MCP server and make it available to supported hosts.

- Node.js (v18 or later): A modern version of Node.js that takes advantage of the latest JavaScript features and performance improvements.
- npm (v7 or later): Ensures compatibility for installing and managing packages.
- VS Code with Dev Containers extension: Allows you to quickly spin up a reproducible development environment, making collaboration easier and more efficient.

A typical file layout for the MCP server template may look like this:

mcp-server/ ├── .devcontainer/ # Dev container configuration │ └── devcontainer.json ├── src/ │ ├── index.ts # MCP Server main entry point │ └── examples/ # Example tool implementations │ ├── calculator.ts # Calculator tool example │ └── rest-api.ts # REST API tool example ├── package.json # Project configuration └── tsconfig.json # TypeScript configuration

The.devcontainerdirectory streamlines container-based development, while thesrc/folder houses the main server logic and examples of custom tools. This structure keeps your project organized and easy to navigate.

To install MCP Server Starter for any supported client:

# For Claude npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client claude # For Cursor npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cursor # For Windsurf npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client windsurf # For Cline npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cline # For TypeScript npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client typescript

- Clone this template: Retrieve the repository files from your preferred source.
- Open in VS Code with Dev Containers: If you have the Dev Containers extension installed, you will be prompted to open this project inside a container.
- Install dependencies:

npm install

MCP tools must return responses in a specific format to ensure proper communication with AI hosts. Here's the structure:

interface ToolResponse { content: ContentItem[]; isError?: boolean; metadata?: Record<string, unknown>; } interface ContentItem { type: string; text?: string; mimeType?: string; data?: unknown; }

- text: Plain text content
- code: Code snippets with optional language specification
- image: Base64-encoded images with MIME type
- file: File content with MIME type
- error: Error messages (whenisErroris true)

return { content: [ { type: "text", text: "Operation completed successfully" }, { type: "code", text: "console.log('Hello, World!')", mimeType: "application/javascript" } ] };

When developing MCP tools, follow these security guidelines:
- Input Validation:

- Always validate input parameters using Zod schemas

- Implement strict type checking
- Sanitize user inputs before processing
- Use thestrict()option in schemas to prevent extra properties

- Never expose internal error details to clients

- Implement proper error boundaries
- Log errors securely
- Return user-friendly error messages

- Implement proper cleanup procedures

- Handle process termination signals
- Close connections and free resources
- Implement timeouts for long-running operations

- Use secure transport protocols

- Implement rate limiting
- Store sensitive data securely
- Use environment variables for configuration

const SecureSchema = z.object({ input: z.string() .min(1) .max(1000) .transform(str => str.trim()) .pipe(z.string().regex(/^[a-zA-Z0-9\s]+$/)) }); server.tool( "secure_tool", SecureSchema.shape, async (params) => { try { // Implement rate limiting await rateLimiter.checkLimit(); // Process validated input const result = await processSecurely(params.input); return { content: [{ type: "text", text: result }] }; } catch (error) { // Log error internally logger.error(error); // Return safe error message return { content: [{ type: "text", text: "An error occurred processing your request" }], isError: true }; } } );

MCP supports streaming responses for long-running operations:

server.tool( "stream_data", StreamSchema.shape, async function* (params) { for (const chunk of dataStream) { yield { content: [{ type: "text", text: chunk }] }; } } );

You can define custom content types for specialized data:

interface CustomContent extends ContentItem { type: "custom"; data: { format: string; value: unknown; }; }

server.tool( "async_operation", AsyncSchema.shape, async (params) => { const operation = await startAsyncOperation(); while (!operation.isComplete()) { await operation.wait(); } return { content: [{ type: "text", text: await operation.getResult() }] }; } );

describe('Calculator Tool', () => { let server: McpServer; beforeEach(() => { server = new McpServer({ name: "test-server", version: "1.0.0" }); registerCalculatorTool(server); }); test('adds numbers correctly', async () => { const result = await server.executeTool('calculate', { a: 5, b: 3, operation: 'add' }); expect(result.content[0].text).toBe('8'); }); });

- Tool registration

- Request/response flow
- Error handling
- Performance metrics

function logMessage(level: 'info' | 'warn' | 'error', message: string) { console.error(\[${level.toUpperCase()}] ${message}\); }

process.on('uncaughtException', (error: Error) => { logMessage('error', \Uncaught error: ${error.message}\); // Implement error reporting });

MCP supports multiple transport protocols:

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const transport = new StdioServerTransport(); await server.connect(transport);

import { WebSocketServerTransport } from "@modelcontextprotocol/sdk/server/websocket.js"; const transport = new WebSocketServerTransport({ port: 3000 }); await server.connect(transport);

import { Transport } from "@modelcontextprotocol/sdk/server/transport.js"; class CustomTransport implements Transport { // Implement transport methods }

const server = new McpServer({ name: "mcp-server", version: "1.0.0", capabilities: { tools: {}, // Enable tools capability streaming: true, // Enable streaming support customContent: ["myFormat"], // Define custom content types metadata: true // Enable metadata support } });

This MCP server template supports multiple AI platforms out of the box:
- Claude Desktop:

- Provides a chat-based environment

- Supports all MCP capabilities
- Ideal for conversational AI interactions

- AI-powered development environment

- Full tool integration support
- Perfect for coding assistance

- Modern AI development platform

- Complete MCP protocol support
- Streamlined workflow integration

- Command-line AI interface

- Tool-focused interactions
- Efficient terminal-based usage

- Native TypeScript support

- Type-safe tool development
- Seamless SDK integration

Each client can be configured using the appropriate Smithery CLI command:

npx -y @smithery/cli run @TheSethRose/mcp-server-starter --client [client-name]

Replace[client-name]with one of:claude,cursor,windsurf,cline, ortypescript.

A convenient way to run this MCP server is through Smithery, a centralized platform for discovering and publishing MCP servers. Smithery simplifies deployment and ensures your server can be integrated into various AI workflows.

You can immediately execute this server via the Smithery CLI:

npx -y @smithery/cli@latest run mcp-server-template --config "{}"

Smithery automatically fetches, installs, and runs the server from its latest release, requiring minimal setup from you.

If you have developed new tools or made local modifications and wish to share them, consider publishing your customized server:
- Create an account onSmithery.
- Follow their deployment instructions to bundle and publish your MCP server.
- Other users can then run your server through Smithery by referencing your unique package name.

{ "mcpServers": { "mcp-server": { "command": "node", "args": [ "/path/to/your/mcp-server/build/index.js" ] } } }

When you interact with Claude Desktop, it can now invoke the MCP tools you have registered. If a user's request aligns with any of your tool's functionality, Claude will prompt to use that tool.
- Use TypeScriptfor better type checking, clearer code organization, and easier maintenance over time.
- Adopt consistent patternsfor implementing tools:

- Keep each tool in its own file

- Use descriptive schemas with proper documentation
- Implement comprehensive error handling
- Return properly formatted content

- Add JSDoc comments to explain functionality

- Document parameters and return types
- Include examples where helpful

- Test tool functionality

- Debug request/response flow
- Verify schema validation
- Check error handling

- Verify input validation

- Test error scenarios
- Check response formatting
- Ensure proper integration with hosts

- Use proper content types

- Implement proper error handling
- Validate all inputs and outputs
- Handle network requests safely
- Format responses consistently

For further information on the MCP ecosystem, refer to:

- Model Context Protocol Documentation: Detailed coverage of MCP architecture, design principles, and more advanced usage examples.
- Smithery - MCP Server Registry: Guidelines for publishing your tools to Smithery and best practices for their registry.
- MCP TypeScript SDK Documentation: Comprehensive documentation of the TypeScript SDK.
- MCP Security Guidelines: Detailed security best practices and recommendations.

- Website:https://www.sethrose.dev
- 𝕏 (Twitter):https://x.com/TheSethRose
- 🦋 (Bluesky):https://bsky.app/profile/sethrose.dev
- Type Safety:

Official Svelte MCP server, provides docs and suggestions on the generated code.