Custom Development

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

Official Documentation: Model Context Protocol · TypeScript SDK

Security Considerations

When building custom MCP servers, follow security best practices including input validation, least-privilege access, and secure credential handling. See Safety Guidelines for details. Remember that any sensitive data an agent can read can be passed on to some other MCP server.

Quickstart

Build and run a working MCP server in under 2 minutes:

# 1. Create project directory
mkdir hello-mcp-server && cd hello-mcp-server

# 2. Initialize package.json
npm init -y

# 3. Install MCP SDK and Zod
npm install @modelcontextprotocol/sdk zod

# 4. Add ES module support to package.json
npm pkg set type=module

Create main.ts with your server code:

// main.ts
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: "hello-server",
  version: "1.0.0",
});

server.registerTool(
  "say_hello",
  {
    description: "Say hello to someone",
    inputSchema: {
      name: z.string().describe("Name to greet"),
    },
    outputSchema: {
      greeting: z.string(),
    },
  },
  async ({ name }) => {
    const output = { greeting: `Hello, ${name}!` };
    return {
      content: [{ type: "text", text: JSON.stringify(output) }],
      structuredContent: output,
    };
  }
);

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

Run and test your server:

# 5. Run the server
npx -y tsx main.ts

# 6. Add to Claude Code (replace with your actual path)
claude mcp add hello-server npx -y tsx /absolute/path/to/main.ts

# 7. Restart Claude Code, then test it:
# > Use the say_hello tool to greet "World"

Extend with more tools using Claude code:

# 8. Switch to plan mode (`Shift+Tab`) and refine the implementation:
> Add a search_duckduckgo tool to main.ts 
that calls https://api.duckduckgo.com/?q={query}&format=json 
and returns the Abstract, AbstractURL and RelatedTopics fields from the response.

# 9. Refine or accept plan

# 10. Restart the server
npx -y tsx main.ts

# 11. Restart Claude Code, then test it:
# > search duckduckgo for "mcp"

Local vs Remote Servers

Local: Runs on your machine as subprocess, stdio transport, direct file system access Remote: Runs on cloud infrastructure, SSE/WebSocket transport, scalable processing

Resources

• MCP Documentation - Complete protocol specification
• TypeScript SDK - Official TypeScript SDK
• Example Servers - Reference implementations

Related

• MCP Overview
• How MCP Works