MCP Server Authoring

What MCP Servers Do

MCP servers expose tools, resources, and prompts to Claude via the Model Context Protocol. They run as separate processes (stdio) or HTTP endpoints that Claude communicates with.

Project Structure (dev-suite)

mcp-servers/{server-name}/ ├── package.json # @dev-suite/{name}, main: dist/index.js ├── tsconfig.json # TypeScript config ├── metadata.json # Server metadata for dev-suite dashboard └── src/ └── index.ts # Server implementation

TypeScript MCP Server Template

See quick-ref/typescript-template.md for the complete starter template.

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

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

// Define a tool server.tool( 'search_docs', // Tool name 'Search documentation by query', // Description { query: z.string(), limit: z.number().optional().default(10) }, // Input schema async ({ query, limit }) => { // Handler const results = await searchDocumentation(query, limit); return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }], }; } );

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

Tool Definition Best Practices

• Name: snake_case, descriptive (search_docs not search )

• Description: clear, includes when to use it

• Input schema: Zod validation with sensible defaults

• Output: Always return content array with type: 'text'

• Errors: Throw errors with descriptive messages — MCP SDK handles formatting

metadata.json (dev-suite specific)

See quick-ref/metadata-schema.md for the complete schema.

{ "name": "my-server", "description": "Full description of what this server does", "shortDescription": "Brief one-liner", "category": "development", "tools": [ { "name": "search_docs", "description": "Search documentation by query" } ], "envVars": [ { "name": "API_KEY", "description": "API key for the service", "required": true } ], "recommendedFor": ["react-expert", "typescript-expert"], "detectedWhen": ["react", "typescript"] }

Transport Types

Transport When to use Config

stdio

Local process, development, CLI tools command

• args in .mcp.json

http

Cloud services, shared servers URL endpoint

sse

Legacy (deprecated) URL endpoint

.mcp.json Configuration

{ "mcpServers": { "my-server": { "command": "node", "args": ["path/to/dist/index.js"], "env": { "API_KEY": "${API_KEY}" } } } }

Environment variables: ${VAR} syntax, ${VAR:-default} for defaults.

Adding to dev-suite

• Create mcp-servers/{name}/ with package.json (@dev-suite/{name} )

• Add metadata.json with tools, envVars, recommendedFor, detectedWhen

• Add src/index.ts with MCP server implementation

• Add tsconfig.json

• Update mcp-servers/package.json workspaces array

• Build: cd mcp-servers && npm install && npm run build

Anti-Patterns

Anti-Pattern Fix

Huge tool output (> 10K tokens) Paginate, filter, or summarize results

No input validation Use Zod schemas for all inputs

Blocking operations without timeout Add timeouts to external calls

Hardcoded credentials Use env vars via process.env

Tool names that are too generic Use specific, descriptive names

Checklist

• Tools have descriptive names (snake_case) and clear descriptions

• Input schemas use Zod with validation and defaults

• Error handling with descriptive messages

• Environment variables for credentials

• metadata.json complete (for dev-suite)

• Package.json added to workspaces

• Builds successfully: npm run build

• Output stays under 10K tokens per tool call

Reference

• TypeScript MCP server template

• metadata.json schema