MCP-Server-Starter

What is MCP?

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.

Core Components

• 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.

TypeScript Implementation

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.

Prerequisites

• 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.

Project Structure

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 `.devcontainer` directory streamlines container-based development, while the `src/` folder houses the main server logic and examples of custom tools. This structure keeps your project organized and easy to navigate.

Quick Start

Installing via Smithery

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

1. Clone this template: Retrieve the repository files from your preferred source.

2. 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.

3. Install dependencies:

npm install

This command fetches and installs all required packages for the MCP server.

4. Build the project:

npm run build

This compiles your TypeScript code into JavaScript, preparing it for runtime.

Development Scripts

• Build the project:

npm run build

Compiles your TypeScript source and sets file permissions for the main entry point.

• Watch mode:

npm run watch

Automatically recompiles TypeScript files whenever changes are made, ideal for active development.

• Run with inspector:

npm run inspector

Launches the server alongside a debugging tool, enabling you to trace issues, set breakpoints, and inspect variables in real time.

Tool Response Format

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;
}

interface ContentItem {
  type: string;
  text?: string;
  mimeType?: string;
  data?: unknown;
}

Supported content types include:

• `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 (when `isError` is true)

Example response:

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

Security Best Practices

When developing MCP tools, follow these security guidelines:

1. Input Validation:

2. Error Handling:

3. Resource Management:

4. API Security:

Example secure tool implementation:

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
      };
    }
  }
);

Advanced Features

Streaming Responses

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
        }]
      };
    }
  }
);

Custom Content Types

You can define custom content types for specialized data:

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

Async Tool Execution

Implement proper async handling:

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()
      }]
    };
  }
);

Testing & Debugging

Unit Testing

Use Jest for testing your tools:

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');
  });
});

Debugging Tools

1. MCP Inspector:

npm run inspector

Provides real-time inspection of:

2. Logging:

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

3. Error Tracking:

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

Transport Configuration

MCP supports multiple transport protocols:

stdio Transport

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);

WebSocket Transport

import { WebSocketServerTransport } from "@modelcontextprotocol/sdk/server/websocket.js";

const transport = new WebSocketServerTransport({
  port: 3000
});
await server.connect(transport);

Custom Transport

import { Transport } from "@modelcontextprotocol/sdk/server/transport.js";

class CustomTransport implements Transport {
  // Implement transport methods
}

Server Capabilities

Configure server capabilities:

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
  }
});

Integration with MCP Hosts

Multi-Client Support

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

1. Claude Desktop:

2. Cursor:

3. Windsurf:

4. Cline:

5. TypeScript:

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`, or `typescript`.

Smithery Integration

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.

Quick Run

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.

Publishing Your Own Version

If you have developed new tools or made local modifications and wish to share them, consider publishing your customized server:

1. Create an account on Smithery.

2. Follow their deployment instructions to bundle and publish your MCP server.

3. Other users can then run your server through Smithery by referencing your unique package name.

Smithery offers:

• A centralized registry to discover and share MCP servers.
• Simplified deployment, removing repetitive setup.
• A community-driven approach where developers contribute diverse tools.
• Easy integration with popular AI hosts.

For additional guidance:

• Smithery Documentation
• Smithery GitHub

Cursor Integration

Cursor is another AI development environment that supports MCP. To incorporate your server into Cursor:

1. Build your server:

npm run build

Ensure an executable `index.js` is generated in the `build` directory.

2. In Cursor, go to `Settings` > `Features` > `MCP`:

Add a new MCP server.

3. Register your server:

4. Save your configuration.

Cursor then detects and lists your tools. During AI-assisted coding sessions or prompt-based interactions, it will call your MCP tools whenever relevant. You can also instruct the AI to use a specific tool by name.

Claude Desktop Integration

Claude Desktop provides a chat-based environment where you can leverage MCP tools. To include your server:

1. Build your server:

npm run build

Confirm that no errors occur and that the main script is generated in `build`.

2. Modify `claude_desktop_config.json`:

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

Provide the path to your compiled main file along with any additional arguments.

3. Restart Claude Desktop to load the new configuration.

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.

Development Best Practices

1. Use TypeScript for better type checking, clearer code organization, and easier maintenance over time.

2. Adopt consistent patterns for implementing tools:

3. Include thorough documentation:

4. Leverage the inspector for debugging:

npm run inspector

This helps you:

5. Test comprehensively before deployment:

6. Follow MCP best practices:

Learn More

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.

Conclusion

By following this template and best practices, you can quickly build a robust MCP server that opens your tools to a broad range of AI hosts. This expanded approach ensures easier maintenance, better type safety, and a smooth user experience when harnessing the capabilities of modern AI systems.

Credits

Template created by Seth Rose:

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

Best Practices

1. Type Safety:

2. Transport Selection:

3. Capability Management:

4. Security Considerations: