Build Custom MCP Server

Create a custom MCP server that exposes domain-specific tools to AI assistants.

When to Use

• Need to expose custom functionality to Claude Code or Claude Desktop
• Building specialized tools beyond what mcptools provides
• Creating a domain-specific AI assistant integration
• Wrapping existing APIs or services as MCP tools

Inputs

• Required: List of tools to expose (name, description, parameters, behavior)
• Required: Implementation language (Node.js or R)
• Required: Transport type (stdio or HTTP)
• Optional: Authentication requirements
• Optional: Docker packaging needs

Procedure

Step 1: Define Tool Specifications

Before writing code, define each tool:

tools:
  - name: query_database
    description: Execute a read-only SQL query against the analysis database
    parameters:
      query:
        type: string
        description: SQL SELECT query to execute
        required: true
      limit:
        type: integer
        description: Maximum rows to return
        default: 100
    returns: JSON array of result rows

  - name: run_analysis
    description: Execute a predefined statistical analysis by name
    parameters:
      analysis_name:
        type: string
        description: Name of the analysis to run
        enum: [descriptive, regression, survival]
      dataset:
        type: string
        description: Dataset identifier
        required: true

Expected: A YAML or markdown specification for each tool with name, description, parameters (including types, defaults, and required flags), and return type documented before writing any code.

On failure: If tool specifications are unclear, interview the domain expert or review the existing API documentation to determine parameter types and return formats.

Step 2: Implement in Node.js (Using MCP SDK)

// server.js
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-analysis-server",
  version: "1.0.0",
});

// Define tools
server.tool(
  "query_database",
  "Execute a read-only SQL query against the analysis database",
  {
    query: z.string().describe("SQL SELECT query"),
    limit: z.number().default(100).describe("Max rows to return"),
  },
  async ({ query, limit }) => {
    // Validate read-only
    if (!/^\s*SELECT/i.test(query)) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries allowed" }],
        isError: true,
      };
    }

    const results = await executeQuery(query, limit);
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);

server.tool(
  "run_analysis",
  "Execute a predefined statistical analysis",
  {
    analysis_name: z.enum(["descriptive", "regression", "survival"]),
    dataset: z.string().describe("Dataset identifier"),
  },
  async ({ analysis_name, dataset }) => {
    const result = await runAnalysis(analysis_name, dataset);
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

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

Expected: A working

server.js

file that imports the MCP SDK, defines tools with Zod schemas, and connects via stdio transport. Running

node server.js

starts the server without errors.

On failure: Verify that

@modelcontextprotocol/sdk

and

zod

are installed (

npm install

). Check that the import paths match the SDK version (the SDK reorganized exports between versions).

Step 3: Implement in R (Using mcptools)

# server.R
library(mcptools)

# Register custom tools
mcp_tool(
  name = "query_database",
  description = "Execute a read-only SQL query",
  parameters = list(
    query = list(type = "string", description = "SQL SELECT query"),
    limit = list(type = "integer", description = "Max rows", default = 100)
  ),
  handler = function(query, limit = 100) {
    if (!grepl("^\\s*SELECT", query, ignore.case = TRUE)) {
      stop("Only SELECT queries allowed")
    }
    result <- DBI::dbGetQuery(con, paste(query, "LIMIT", limit))
    jsonlite::toJSON(result, auto_unbox = TRUE)
  }
)

# Start server
mcptools::mcp_server()

Expected: A working

server.R

file that registers custom tools with

mcp_tool()

and starts the server with

mcp_server()

. Running

Rscript server.R

starts the MCP server.

On failure: Ensure

mcptools

is installed from GitHub (

remotes::install_github("posit-dev/mcptools")

). Check that the handler function signatures match the parameter definitions.

Step 4: Set Up Project Structure

my-mcp-server/
├── package.json          # Node.js dependencies
├── server.js             # Server implementation
├── tools/                # Tool implementations
│   ├── database.js
│   └── analysis.js
├── test/                 # Tests
│   └── tools.test.js
├── Dockerfile            # Container packaging
└── README.md             # Setup instructions

Expected: Project directory created with

server.js

(or

server.R

),

package.json

,

tools/

directory for modular tool implementations, and

test/

directory for tests.

On failure: If the directory structure doesn't match your implementation language, adjust accordingly. R servers may use

R/

instead of

tools/

and

tests/testthat/

instead of

test/

.

Step 5: Test the Server

Manual testing with stdio:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node server.js

Register with Claude Code:

claude mcp add my-server stdio "node" "/path/to/server.js"

Verify tools appear:

Start a Claude Code session and check that custom tools are listed and functional.

Expected: The

tools/list

JSON-RPC call returns all defined tools with correct names and schemas.

claude mcp list

shows the server registered. Tools are callable from a Claude Code session.

On failure: If

tools/list

returns an empty array, the tools were not registered before

server.connect()

. If Claude Code cannot find the server, verify the command path in

claude mcp add

is absolute and the binary is executable.

Step 6: Add Error Handling

server.tool("risky_operation", "...", schema, async (params) => {
  try {
    const result = await performOperation(params);
    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
    };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Error: ${error.message}` }],
      isError: true,
    };
  }
});

Expected: Each tool handler is wrapped in try/catch. Invalid inputs return

isError: true

with a descriptive message instead of crashing the server process.

On failure: If the server still crashes on bad input, check that the try/catch wraps the entire handler body including any async operations. Ensure promises are awaited within the try block.

Step 7: Package for Distribution

Create a

package.json

with a bin entry:

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "bin": {
    "my-mcp-server": "./server.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  }
}

Users can then install and configure:

npm install -g my-mcp-server
claude mcp add my-server stdio "my-mcp-server"

Expected: A

package.json

with a

bin

entry pointing to the server entry point. Users can install globally with

npm install -g

and register with

claude mcp add

.

On failure: If the bin entry doesn't work after global install, ensure

server.js

has a shebang line (

#!/usr/bin/env node

) and is marked executable. Verify the package name doesn't conflict with existing npm packages.

Validation

• Server starts without errors

• tools/list

  returns all defined tools with correct schemas
• Each tool executes correctly with valid input
• Tools return appropriate errors for invalid input
• Server works with Claude Code via stdio transport
• Tools are discoverable and usable in Claude sessions

Common Pitfalls

• Blocking operations: MCP servers should handle requests asynchronously. Long-running operations block other tool calls.
• Missing error handling: Unhandled exceptions crash the server. Always wrap tool handlers in try/catch.
• Schema mismatches: Tool parameter schemas must exactly match what the handler expects
• stdio buffering: When using stdio transport, ensure output is flushed. Node.js buffers stdout by default.
• Security: MCP servers have the same access as the process. Validate inputs carefully, especially for shell commands or database queries.

Related Skills

• configure-mcp-server

  - connect the built server to clients

• troubleshoot-mcp-connection

  - debug connectivity issues

• containerize-mcp-server

  - package the server in Docker