The MCP TypeScript SDK: A Complete Guide to Tools, Resources, Prompts, and Beyond

npx @agentailor/create-mcp-server --name=my-mcp-server

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

npx tsc --init

// Server classes
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { Server } from '@modelcontextprotocol/sdk/server/index.js'

// Transports
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'

// Types
import type {
  CallToolResult,
  GetPromptResult,
  ReadResourceResult,
} from '@modelcontextprotocol/sdk/types.js'

// Utilities
import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'

import { completable } from '@modelcontextprotocol/sdk/server/completable.js'

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
})

server.registerTool(
  'greet',
  {
    description: 'Greet a user by name',
    inputSchema: {
      name: z.string().describe('The name to greet'),
    },
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}!` }],
  })
)

import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'

const server = new Server({ name: 'my-server', version: '1.0.0' }, { capabilities: { tools: {} } })

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'greet',
      description: 'Greet a user by name',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'The name to greet' },
        },
        required: ['name'],
      },
    },
  ],
}))

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'greet') {
    const { name } = request.params.arguments as { name: string }
    return {
      content: [{ type: 'text', text: `Hello, ${name}!` }],
    }
  }
  throw new Error('Tool not found')
})

const server = new Server(
  { name: 'my-server', version: '1.0.0' },
  {
    capabilities: {
      tools: {},
      resources: {},
      prompts: {},
      logging: {},
    },
  }
)

import fs from 'fs/promises'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

const server = new McpServer({ name: 'file-server', version: '1.0.0' })

server.registerTool(
  'read_file',
  {
    description: `Read the contents of a file from the filesystem.

Use this tool when you need to:
- Examine source code or configuration files
- Read log files for debugging
- Access any text-based file`,
    inputSchema: {
      path: z.string().describe('Absolute path to the file to read'),
      encoding: z
        .enum(['utf-8', 'ascii', 'base64'])
        .default('utf-8')
        .describe('File encoding to use'),
    },
  },
  async ({ path, encoding }) => {
    const content = await fs.readFile(path, encoding)
    return {
      content: [{ type: 'text', text: content }],
    }
  }
)

server.registerTool(
  'search',
  {
    description: 'Search for items with filters',
    inputSchema: {
      // Basic types
      query: z.string().min(1).describe('Search query'),
      limit: z.number().int().positive().max(100).default(10).describe('Max results'),
      includeArchived: z.boolean().default(false).describe('Include archived items'),

      // Enums for constrained choices
      sortBy: z.enum(['relevance', 'date', 'name']).default('relevance').describe('Sort order'),

      // Optional fields
      category: z.string().optional().describe('Filter by category'),

      // Arrays
      tags: z.array(z.string()).default([]).describe('Filter by tags'),

      // Custom validation
      dateRange: z
        .object({
          start: z.string().date().describe('Start date (YYYY-MM-DD)'),
          end: z.string().date().describe('End date (YYYY-MM-DD)'),
        })
        .optional()
        .describe('Filter by date range'),
    },
  },
  async (args) => {
    // args is fully typed and validated
    const results = await performSearch(args)
    return {
      content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
    }
  }
)

server.registerTool(
  'get_user',
  {
    description: 'Get user profile by ID',
    inputSchema: {
      userId: z.string().describe('The user ID to look up'),
    },
  },
  async ({ userId }) => {
    const user = await db.users.findById(userId)

    if (!user) {
      return {
        content: [
          {
            type: 'text',
            text: `User "${userId}" not found. Verify the ID is correct or try searching by name instead.`,
          },
        ],
        isError: true,
      }
    }

    return {
      content: [{ type: 'text', text: JSON.stringify(user, null, 2) }],
    }
  }
)

import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'

server.registerTool(
  'delete_record',
  {
    description: 'Delete a record by ID',
    inputSchema: {
      id: z.string().describe('Record ID'),
      confirm: z.boolean().describe('Must be true to confirm deletion'),
    },
  },
  async ({ id, confirm }) => {
    if (!confirm) {
      throw new McpError(ErrorCode.InvalidParams, 'Deletion requires confirm: true')
    }

    await db.records.delete(id)
    return {
      content: [{ type: 'text', text: `Record ${id} deleted.` }],
    }
  }
)

server.registerTool(
  'list_files',
  {
    description: 'List files in a directory',
    inputSchema: {
      path: z.string().describe('Directory path'),
    },
    annotations: {
      readOnlyHint: true, // This tool only reads data
      destructiveHint: false, // No destructive side effects
      idempotentHint: true, // Same input always gives same output
      openWorldHint: false, // Operates on local resources only
    },
  },
  async ({ path }) => {
    // implementation
  }
)

server.registerTool(
  'delete_file',
  {
    description: 'Delete a file from the filesystem',
    inputSchema: {
      path: z.string().describe('Path to the file to delete'),
    },
    annotations: {
      readOnlyHint: false,
      destructiveHint: true, // This deletes data
      idempotentHint: true, // Deleting twice has same effect
      openWorldHint: false,
    },
  },
  async ({ path }) => {
    // implementation
  }
)

server.registerResource(
  'server-config',
  'config://server',
  {
    description: 'Current server configuration',
    mimeType: 'application/json',
  },
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(
          {
            maxConnections: 100,
            timeout: 30000,
            environment: process.env.NODE_ENV,
          },
          null,
          2
        ),
      },
    ],
  })
)

import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'

server.registerResource(
  'user-profile',
  new ResourceTemplate('users://{userId}/profile', { list: undefined }),
  {
    description: 'User profile data by user ID',
    mimeType: 'application/json',
  },
  async (uri, { userId }) => {
    const user = await db.users.findById(userId)
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: 'application/json',
          text: JSON.stringify(user, null, 2),
        },
      ],
    }
  }
)

new ResourceTemplate('users://{userId}/profile', {
  list: async () => {
    const users = await db.users.findAll()
    return users.map((user) => ({
      uri: `users://${user.id}/profile`,
      name: `Profile: ${user.name}`,
    }))
  },
})

// After adding a new resource dynamically
server.sendResourceListChanged()

server.registerPrompt(
  'code-review',
  {
    description: 'Review code for best practices, bugs, and improvements',
    argsSchema: {
      language: z
        .enum(['typescript', 'python', 'go', 'rust'])
        .describe('Programming language of the code'),
      code: z.string().describe('The code to review'),
      focus: z
        .enum(['security', 'performance', 'readability', 'all'])
        .default('all')
        .describe('What aspect to focus the review on'),
    },
  },
  async ({ language, code, focus }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Review this ${language} code with a focus on ${focus}:\n\n\`\`\`${language}\n${code}\n\`\`\``,
        },
      },
    ],
  })
)

server.registerPrompt(
  'debug-issue',
  {
    description: 'Structured debugging workflow for reported issues',
    argsSchema: {
      error: z.string().describe('The error message or description'),
      context: z.string().optional().describe('Additional context about when the error occurs'),
    },
  },
  async ({ error, context }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `I'm encountering this error: ${error}${context ? `\n\nContext: ${context}` : ''}`,
        },
      },
      {
        role: 'assistant',
        content: {
          type: 'text',
          text: "I'll help debug this. Let me start by analyzing the error and identifying possible causes.",
        },
      },
      {
        role: 'user',
        content: {
          type: 'text',
          text: 'Please check the relevant logs and source code, then suggest a fix with code examples.',
        },
      },
    ],
  })
)

server.registerTool(
  'summarize_url',
  {
    description: 'Fetch a URL and return an AI-generated summary',
    inputSchema: {
      url: z.string().url().describe('URL to fetch and summarize'),
      style: z
        .enum(['brief', 'detailed', 'bullet-points'])
        .default('brief')
        .describe('Summary style'),
    },
  },
  async ({ url, style }, { server: serverInstance }) => {
    // Step 1: Fetch the content
    const response = await fetch(url)
    const html = await response.text()

    // Step 2: Ask the client's LLM to summarize it
    const summary = await serverInstance.createMessage({
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Summarize the following web page content in ${style} style:\n\n${html.slice(0, 10000)}`,
          },
        },
      ],
      maxTokens: 500,
    })

    return {
      content: [
        {
          type: 'text',
          text:
            summary.content.type === 'text' ? summary.content.text : 'Unable to generate summary',
        },
      ],
    }
  }
)

const result = await serverInstance.createMessage({
  messages: [{ role: 'user', content: { type: 'text', text: 'Classify this text...' } }],
  modelPreferences: {
    hints: [{ name: 'claude-3-5-haiku' }, { name: 'claude' }],
    costPriority: 0.8, // Prefer cheaper models
    speedPriority: 0.9, // Prefer faster models
    intelligencePriority: 0.3, // Don't need the smartest model
  },
  maxTokens: 100,
})

import { completable } from '@modelcontextprotocol/sdk/server/completable.js'

server.registerPrompt(
  'translate',
  {
    description: 'Translate text to a target language',
    argsSchema: {
      language: completable(z.string().describe('Target language'), async (value) => {
        const languages = [
          'English',
          'Spanish',
          'French',
          'German',
          'Japanese',
          'Korean',
          'Chinese',
          'Portuguese',
          'Italian',
          'Dutch',
        ]
        return languages.filter((l) => l.toLowerCase().startsWith(value.toLowerCase()))
      }),
      text: z.string().describe('Text to translate'),
    },
  },
  async ({ language, text }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Translate the following text to ${language}:\n\n${text}`,
        },
      },
    ],
  })
)

server.registerResource(
  'project-docs',
  new ResourceTemplate('docs://{projectName}/{docType}', {
    list: undefined,
  }),
  {
    description: 'Project documentation',
    mimeType: 'text/markdown',
  },
  async (uri, { projectName, docType }) => {
    // handler
  }
)

server.registerTool(
  'scan_project',
  {
    description: 'Scan the project for issues',
    inputSchema: {},
  },
  async (_args, { server: serverInstance }) => {
    const { roots } = await serverInstance.listRoots()

    if (roots.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: 'No project roots configured. Ask the user to set a root directory.',
          },
        ],
        isError: true,
      }
    }

    const results = []
    for (const root of roots) {
      results.push(`Scanning: ${root.uri} (${root.name || 'unnamed'})`)
      // Perform analysis on each root...
    }

    return {
      content: [{ type: 'text', text: results.join('\n') }],
    }
  }
)

const server = new McpServer(
  { name: 'my-server', version: '1.0.0' },
  { capabilities: { logging: {} } }
)

server.registerTool(
  'process_data',
  {
    description: 'Process a dataset',
    inputSchema: {
      datasetId: z.string().describe('Dataset identifier'),
    },
  },
  async ({ datasetId }, { log }) => {
    log.info(`Starting processing for dataset: ${datasetId}`)

    try {
      const data = await fetchDataset(datasetId)
      log.debug(`Loaded ${data.length} records`)

      const result = await transform(data)
      log.info(`Processing complete: ${result.processedCount} records transformed`)

      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      }
    } catch (error) {
      log.error(`Processing failed: ${error.message}`)
      return {
        content: [{ type: 'text', text: `Processing failed: ${error.message}` }],
        isError: true,
      }
    }
  }
)

// Dynamically add a tool based on runtime conditions
server.registerTool(
  'new_capability',
  {
    /* ... */
  },
  async () => {
    /* ... */
  }
)
server.sendToolListChanged()

// Same for resources and prompts
server.sendResourceListChanged()
server.sendPromptListChanged()

server.registerTool(
  'bulk_import',
  {
    description: 'Import records from a CSV file',
    inputSchema: {
      filePath: z.string().describe('Path to the CSV file'),
    },
  },
  async ({ filePath }, { reportProgress }) => {
    const records = await parseCSV(filePath)
    const total = records.length
    let processed = 0

    for (const record of records) {
      await importRecord(record)
      processed++
      await reportProgress({ progress: processed, total })
    }

    return {
      content: [{ type: 'text', text: `Imported ${processed} records.` }],
    }
  }
)

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = new McpServer({ name: 'my-server', version: '1.0.0' })

// Register tools, resources, prompts...

const transport = new StdioServerTransport()
await server.connect(transport)
console.error('Server running on stdio') // stderr only!

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js'

const app = createMcpExpressApp({
  allowedHosts: ['localhost', '127.0.0.1', '[::1]'],
})

const server = new McpServer({ name: 'my-server', version: '1.0.0' })

// Register tools, resources, prompts...

// The transport handles sessions, SSE streaming, and routing
app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() })
  await server.connect(transport)
  await transport.handleRequest(req, res)
})

app.listen(3000, () => console.log('Server running on http://localhost:3000/mcp'))

import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'

// Bad: generic error
return { content: [{ type: 'text', text: 'Error occurred' }], isError: true }

// Good: actionable error
return {
  content: [
    {
      type: 'text',
      text: `File "${path}" not found. Check that the path is absolute and the file exists. Available files in the directory: ${availableFiles.join(', ')}`,
    },
  ],
  isError: true,
}

import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'
import { z } from 'zod'

// In-memory document store
interface Document {
  id: string
  title: string
  content: string
  tags: string[]
  createdAt: string
  updatedAt: string
}

const documents = new Map<string, Document>()

export function getServer() {
  const server = new McpServer(
    { name: 'knowledge-base', version: '1.0.0' },
    { capabilities: { logging: {} } }
  )

  // --- Tools ---

  server.registerTool(
    'search_documents',
    {
      description: `Search the knowledge base for documents matching a query.
Returns matching documents with their IDs, titles, and relevance snippets.
Use this to find documents before reading their full content via resources.`,
      inputSchema: {
        query: z.string().min(1).describe('Search query'),
        tags: z.array(z.string()).default([]).describe('Filter by tags'),
        limit: z.number().int().positive().max(50).default(10).describe('Max results'),
      },
      annotations: { readOnlyHint: true },
    },
    async ({ query, tags, limit }, { log }) => {
      log.info(`Searching for: "${query}" with tags: [${tags.join(', ')}]`)

      const results = Array.from(documents.values())
        .filter((doc) => {
          const matchesQuery =
            doc.title.toLowerCase().includes(query.toLowerCase()) ||
            doc.content.toLowerCase().includes(query.toLowerCase())
          const matchesTags = tags.length === 0 || tags.some((t) => doc.tags.includes(t))
          return matchesQuery && matchesTags
        })
        .slice(0, limit)

      log.info(`Found ${results.length} results`)

      return {
        content: [
          {
            type: 'text',
            text:
              results.length > 0
                ? results
                    .map((doc) => `[${doc.id}] ${doc.title} (tags: ${doc.tags.join(', ')})`)
                    .join('\n')
                : 'No documents found. Try broadening your search query or removing tag filters.',
          },
        ],
      }
    }
  )

  server.registerTool(
    'create_document',
    {
      description: 'Create a new document in the knowledge base',
      inputSchema: {
        title: z.string().min(1).describe('Document title'),
        content: z.string().min(1).describe('Document content (markdown supported)'),
        tags: z.array(z.string()).default([]).describe('Tags for categorization'),
      },
      annotations: { readOnlyHint: false },
    },
    async ({ title, content, tags }, { log }) => {
      const id = `doc_${Date.now()}`
      const now = new Date().toISOString()

      const doc: Document = { id, title, content, tags, createdAt: now, updatedAt: now }
      documents.set(id, doc)

      log.info(`Created document: ${id} - "${title}"`)
      server.sendResourceListChanged()

      return {
        content: [
          {
            type: 'text',
            text: `Document created successfully.\nID: ${id}\nTitle: ${title}\nTags: ${tags.join(', ') || 'none'}`,
          },
        ],
      }
    }
  )

  // --- Resources ---

  server.registerResource(
    'document',
    new ResourceTemplate('kb://documents/{documentId}', {
      list: async () =>
        Array.from(documents.values()).map((doc) => ({
          uri: `kb://documents/${doc.id}`,
          name: doc.title,
        })),
    }),
    {
      description: 'Full document content by ID',
      mimeType: 'text/markdown',
    },
    async (uri, { documentId }) => {
      const doc = documents.get(documentId)
      if (!doc) {
        throw new McpError(ErrorCode.InvalidParams, `Document "${documentId}" not found`)
      }

      return {
        contents: [
          {
            uri: uri.href,
            mimeType: 'text/markdown',
            text: `# ${doc.title}\n\n**Tags:** ${doc.tags.join(', ') || 'none'}\n**Created:** ${doc.createdAt}\n**Updated:** ${doc.updatedAt}\n\n---\n\n${doc.content}`,
          },
        ],
      }
    }
  )

  // --- Prompts ---

  server.registerPrompt(
    'summarize-document',
    {
      description: 'Generate a concise summary of a knowledge base document',
      argsSchema: {
        documentId: z.string().describe('ID of the document to summarize'),
        style: z
          .enum(['executive', 'technical', 'bullet-points'])
          .default('executive')
          .describe('Summary style'),
      },
    },
    async ({ documentId, style }) => {
      const doc = documents.get(documentId)
      if (!doc) {
        return {
          messages: [
            {
              role: 'user',
              content: {
                type: 'text',
                text: `Document "${documentId}" not found. Please search for the correct document ID first.`,
              },
            },
          ],
        }
      }

      return {
        messages: [
          {
            role: 'user',
            content: {
              type: 'text',
              text: `Provide a ${style} summary of the following document:\n\n# ${doc.title}\n\n${doc.content}`,
            },
          },
        ],
      }
    }
  )

  return server
}