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

mcp-authoring