Mcp Server Ts

TypeScript MCP Server Builder

Build MCP (Model Context Protocol) servers in TypeScript by referencing code snippets from the official Everything reference server.

How It Works

1. Browse the snippet catalog below or in snippets/
2. Copy the snippets you need into your project
3. Customize the copied code for your use case
4. Register your tools/resources/prompts with the server

Snippets are bundled in this skill's snippets/ directory.

---

Quick Start Decision Trees

What MCP Primitive Should I Use?

Need to perform actions with side effects?
  └─> Is it a long-running operation (>2-3 seconds)?
      └─> Use TASKS (async execution with polling)
          Examples: Research queries, data processing, report generation
  └─> Is it quick and synchronous?
      └─> Use TOOLS (model-controlled)
          Examples: API calls, file operations, computations

Need to expose data for LLM context?
  └─> Is data relatively static or URI-addressable?
      └─> Use RESOURCES (application-controlled)
          Examples: file contents, database records, API responses
  └─> Need parameterized access patterns?
      └─> Use Resource Templates with URI variables
          Example: myapp://users/{userId}/profile

Need user-initiated commands/slash commands?
  └─> Use PROMPTS (user-controlled)
      Examples: /summarize, /translate, /analyze

What Transport Should I Use?

Local integration (subprocess, CLI, Claude Desktop)?
  └─> Use stdio transport (default)

Remote service, multi-client, or web deployment?
  └─> Use Streamable HTTP transport

> Logging with stdio transport: Never use console.log() in stdio servers - it writes to stdout, which is reserved for MCP protocol messages and will break communication. Use console.error() for all diagnostic output (it writes to stderr).

---

Phase 1: Research

1.1 Identify Your Integration

Before writing code, understand:

• What API/service are you integrating?
• What operations do users need to perform?
• What data should be exposed to the LLM?

1.2 Browse Available Snippets

Review the snippet catalog below to identify patterns that match your needs:

| Snippet | Description | Best For | |---------|-------------|----------| | server-setup | Basic McpServer with stdio | Starting any new server | | server-setup-tasks | McpServer with Tasks capability | Servers needing async operations | | tool-basic | Simple tool with Zod schema | API calls, simple operations | | tool-progress | Tool with progress notifications | Long-running operations (sync) | | tool-annotations | Tool with semantic hints | Indicating read-only/destructive ops | | tool-output-schema | Tool with structured output | Typed responses | | tool-agentic-sampling | Agentic tool with LLM sampling loop | Server-driven AI workflows | | tool-resource-links | Tool returning resource_link blocks | Deferred resource resolution | | tool-image | Tool returning image content | Image responses | | tool-elicitation | Standalone elicitation request | User input forms | | tool-sampling-simple | Simple one-shot sampling | Quick LLM requests | | task-tool-basic | Task with multi-stage progress and cancellation | Async long-running operations | | task-input-required | Task with elicitation and cancellation | Operations needing user clarification | | resource-static | Static resource registration | Files, configs, static data | | resource-template | Dynamic URI template resource | Parameterized data access | | resource-session | Session-scoped temporary resource | Dynamic/computed data | | resource-collection | Collection returning multiple items | Indexes, composite resources | | prompt-basic | Simple prompt | Basic user commands | | prompt-args | Prompt with arguments | Parameterized commands | | prompt-completions | Context-aware argument completions | Dependent argument values | | prompt-resource | Prompt with embedded resources | Resource-based prompts |

1.3 Check Client Compatibility

Use the MCP docs server to look up current client capabilities:

• Query for "Example clients" to get a full list of clients and supported features
• Query for the client name that you'd like to use
• Check transport support (stdio vs Streamable HTTP)
• Verify feature support (tools, resources, prompts, sampling, etc.)

---

Phase 2: Implement

2.1 Initialize Project

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init

Update tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  }
}

Update package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

2.2 Add Snippets

Copy snippets from this skill's snippets/ directory into your project. The snippets are organized by category:

snippets/
├── server/
│   ├── index.ts              # Server setup
│   └── index-with-tasks.ts   # Server setup with Tasks
├── tools/                    # Tool examples
│   ├── echo.ts
│   ├── trigger-long-running-operation.ts
│   ├── get-annotated-message.ts
│   ├── get-structured-content.ts
│   ├── agentic-sampling.ts
│   ├── get-resource-links.ts
│   ├── get-tiny-image.ts
│   ├── trigger-elicitation-request.ts
│   └── trigger-sampling-request.ts
├── tasks/                    # Task examples (SEP-1686)
│   ├── task-tool-basic.ts
│   └── task-input-required.ts
├── resources/                # Resource examples
│   ├── files.ts
│   ├── templates.ts
│   ├── session.ts
│   └── collection.ts
└── prompts/                  # Prompt examples
    ├── simple.ts
    ├── args.ts
    ├── completions.ts
    └── resource.ts

Copy snippets directly:

cp snippets/server/index.ts /path/to/my-mcp-server/src/
cp snippets/tools/echo.ts /path/to/my-mcp-server/src/

2.3 Customize and Register

Each snippet includes:

• Source URL linking to the original GitHub file
• Working code ready to customize

Modify the copied code:

1. Update tool/resource/prompt names
2. Adjust schemas for your API
3. Implement your business logic
4. Register with your server

---

Phase 3: Test

3.1 Build

npm run build

3.2 Test with MCP Inspector

npx @modelcontextprotocol/inspector@latest node dist/index.js

The Inspector lets you:

• List and call tools
• Browse resources
• Test prompts
• View server logs

3.3 Quality Checklist

• [ ] All tools have clear descriptions
• [ ] Input schemas validate correctly
• [ ] Error messages are actionable
• [ ] Long operations report progress
• [ ] Resources use appropriate MIME types

3.4 Writing Good Tool Descriptions

When an LLM client connects to your server, it uses your tool descriptions to decide which tools to call. Small refinements to descriptions can yield dramatic improvements in tool selection accuracy.

Think like you're onboarding a new hire. Make implicit context explicit—specialized query formats, niche terminology, and expected behaviors should all be clearly stated.

Parameter naming matters:

• Avoid generic names like user → use user_id
• Prefer semantic names (file_type) over technical ones (mime_type)
• Use natural language identifiers over cryptic codes

Provide actionable error messages that guide the agent toward correct usage, not opaque error codes.

// Bad - vague description, unclear parameters
server.registerTool("process", { inputSchema: z.object({ data: z.string() }) }, async ({ data }) => { ... });

// Good - clear purpose, descriptive parameters
server.registerTool(
  "convert_markdown_to_html",
  {
    title: "Convert Markdown to HTML",
    description: "Convert markdown text to HTML for rendering. Use when displaying user-generated content.",
    inputSchema: z.object({ markdown_text: z.string().describe("Raw markdown to convert") }),
  },
  async ({ markdown_text }) => { ... }
);

See: Writing Tools for Agents for more guidance.

---

Available Snippets Catalog

Server Setup

| Name | Description | |------|-------------| | server-setup | Basic McpServer initialization with stdio transport, capabilities declaration, and clean shutdown | | server-setup-tasks | McpServer with Tasks capability, InMemoryTaskStore, and InMemoryTaskMessageQueue |

Tasks (SEP-1686)

| Name | Description | |------|-------------| | task-tool-basic | Task with multi-stage progress, cancellation, and createTask/getTask/getTaskResult/cancelTask handlers | | task-input-required | Task with input_required status, elicitation side-channel, multi-stage progress, and cancellation |

Tools

| Name | Description | |------|-------------| | tool-basic | Simple tool with Zod input schema (echo pattern) | | tool-progress | Long-running operation with progress notifications | | tool-annotations | Tool with readOnlyHint, destructiveHint, idempotentHint | | tool-output-schema | Tool with structured output schema for typed responses | | tool-agentic-sampling | Agentic tool using sampling with tools - LLM executes server tools in a loop (MCP 2025-11-25) | | tool-resource-links | Tool returning resource_link content blocks for deferred resolution | | tool-image | Tool returning image content blocks (base64-encoded) | | tool-elicitation | Standalone elicitation request with schema-driven form (client capability check) | | tool-sampling-simple | Simple one-shot sampling request (client capability check) |

Resources

| Name | Description | |------|-------------| | resource-static | Static resource from files or fixed data | | resource-template | Dynamic resource with URI template variables | | resource-session | Session-scoped temporary resources (not persisted) | | resource-collection | Collection resource returning multiple items with distinct URIs |

Prompts

| Name | Description | |------|-------------| | prompt-basic | Simple prompt without arguments | | prompt-args | Prompt with required/optional arguments and auto-completion | | prompt-completions | Prompt with context-aware argument completions using completable() helper | | prompt-resource | Prompt with embedded resource references in messages |

---

Related Skills

This skill focuses on building MCP servers. For connecting to MCP servers, see:

| Skill | Use When | |-------|----------| | mcp-client-ts | Full MCP client (tools, resources, prompts, sampling, roots, logging, tasks) | | claude-agent-sdk-ts | Claude agents (limited MCP: tools + resources only) |

Choose based on which MCP features your server exposes and which the client needs.

---

Reference Files

For deeper guidance, load these reference documents:

• [TypeScript SDK Patterns](./reference/typescriptsdkpatterns.md) - SDK imports, registration patterns, error handling
• [MCP Primitives Guide](./reference/mcpprimitivesguide.md) - Tool, Resource, Prompt specifications from MCP spec
• [MCP Tasks Guide](./reference/mcptasksguide.md) - Task-based async operations (SEP-1686)

---

MCP Documentation Server

For up-to-date client compatibility info and protocol details, use the MCP docs server:

{
  "mcpServers": {
    "mcp-docs": {
      "type": "http",
      "url": "https://modelcontextprotocol.io/mcp"
    }
  }
}

This provides live access to:

• Client capability matrices
• Protocol specification updates
• SDK documentation
• Best practices

---

External Resources

• MCP Specification - Official protocol documentation
• Everything Server - Reference implementation (snippet source)
• TypeScript SDK - Official SDK repository
• MCP Inspector - Testing tool

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: olaservo
• Source: olaservo/mcp-agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.