TypeScript MCP Server Development

TypeScript MCP Ecosystem

Anthropic provides @anthropic/mcp and related packages; the community also has @modelcontextprotocol/sdk and others. TypeScript MCP servers are well-suited for Node.js backends and frontend tooling.

Core Package Structure

• @anthropic/mcp-core: Protocol definitions, message types, base Server/Client logic
• @anthropic/mcp-server-*: Connectors (stdio, sse, etc.)
• @anthropic/mcp: Aggregated package with ready-to-use Server construction

Server Setup

import { MCPServer } from "@anthropic/mcp";
import { StdioServerTransport } from "@anthropic/mcp-server-stdio";
const server = new MCPServer({
  name: "my-server",
  tools: {
    search: {
      description: "Search documents",
      inputSchema: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
      handler: async ({ query }) => {
        return await doSearch(query);
      },
    },
  },
  resources: {
    "doc://readme": {
      description: "README content",
      handler: async () => readFile("README.md", "utf-8"),
    },
  },
});
const transport = new StdioServerTransport();
server.connect(transport);

Connectors

• StdioServerTransport: stdin/stdout; for Claude Desktop, Cursor, and other local integrations
• SSEServerTransport: HTTP + SSE; for remote services
• WebSocket: Some implementations support WebSocket transport

Switching transport only requires replacing the Connector; business logic stays the same.

Tool Definition Conventions

• inputSchema: Follow JSON Schema; define parameter types, required fields, defaults
• description: Clear description of purpose and use cases; affects model selection
• handler: Async function; receives parsed parameters and returns serializable results

Resources and Prompts

• resources: Map URI or template to description and handler
• prompts: Provide template name, description, parameters, and content generation logic

Error Handling

• throw new Error("message") in handlers becomes MCP error responses
• Define custom error types for differentiated handling on the client

Development and Debugging

• Run TypeScript directly with npx tsx or ts-node
• Use LANGCHAIN_TRACING or MCP client logs to inspect requests and responses
• Unit tests can mock transport and call the server's handlers directly

Summary

TypeScript MCP servers built on @anthropic/mcp-core and Connectors provide type-safe, extensible development. Once you master tool, resource, and prompt registration and Connector switching, you can quickly build MCP services for Claude Desktop, Cursor, and other clients.