Custom Development

Build your own MCP servers to extend Claude Code with specialized capabilities for your unique workflow needs.

When to Build Custom Servers

Create a custom MCP server for:

• Unique integrations - Your tool or service isn't supported
• Proprietary systems - Internal APIs or databases
• Specialized workflows - Company-specific processes
• Security requirements - Data must stay within your infrastructure

Hello World Example

Get started with a minimal working TypeScript server:

// hello-server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

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

server.setRequestHandler('tools/list', async () => {
  return {
    tools: [{
      name: 'say_hello',
      description: 'Say hello to someone',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Name to greet' }
        },
        required: ['name']
      }
    }]
  };
});

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'say_hello') {
    const { name } = request.params.arguments;
    return {
      content: [{ type: 'text', text: `Hello, ${name}!` }]
    };
  }
  throw new Error('Unknown tool');
});

const transport = new StdioServerTransport();
server.connect(transport);

Setup and Testing

Create a complete development workflow in minutes:

Prerequisites

# Install the MCP SDK
npm install @modelcontextprotocol/sdk

Local Development

Test your server locally before installing:

# 1. Create and test locally
mkdir my-mcp-server
cd my-mcp-server

# Initialize project
npm init -y
npm install @modelcontextprotocol/sdk

# Save your server as server.js

# 2. Test the server independently
node server.js

Install for Claude

Add your local server for development:

# TypeScript server
claude mcp add-json my-server '{
  "command": "node", 
  "args": ["/absolute/path/to/server.js"]
}' -s user

# Verify it's working
claude mcp list

Test with Claude

# Start Claude and test your tools
cl

# Claude will now have access to your custom tools
# Try: "Use my say_hello tool to greet Alice"

Local vs Remote MCP Servers

Understanding the two types of MCP server architectures:

Local MCP Servers

Servers that run on your machine and process requests locally:

• Direct execution - Server runs as a subprocess of Claude
• File system access - Can read/write local files directly
• Fast response - No network latency
• Privacy - Data never leaves your machine

# Examples of local servers
claude mcp add-json git '{"command": "uvx", "args": ["mcp-server-git"]}' -s user
claude mcp add-json filesystem '{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"]}' -s user

Remote MCP Servers

Servers that run on external infrastructure and communicate over the network:

• Cloud-based - Server runs on remote infrastructure
• SSE/WebSocket transport - Communicates via network protocols
• Scalable - Can handle heavy processing without local resources
• Shared services - Access to centralized data or APIs

# Examples of remote servers (note the URL-based configuration)
claude mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse -s user
claude mcp add playwright https://mcp.playwright.dev/v1/sse -s user

Key Difference: Local servers run as subprocesses on your machine using stdio transport. Remote servers run on external infrastructure and communicate via SSE (Server-Sent Events) or WebSocket protocols.

Best Practices

Tool Design

• Single purpose - One tool, one job
• Clear descriptions - Help Claude understand usage
• Validate inputs - Check parameters before processing
• Handle errors - Return helpful error messages

Development Workflow

• Start simple - Begin with basic functionality
• Test locally - Verify before installing in Claude
• Add gradually - Build features incrementally
• Document usage - Include examples and descriptions

Security

• Validate inputs - Never trust user data
• Limit scope - Only access what you need
• Handle secrets - Use environment variables
• Log operations - Track what your server does

Community Resources

Official

• MCP Documentation - Complete protocol specification
• SDK Repository - Official SDKs and examples
• Example Servers - Reference implementations