Building Custom MCP Servers & Tools

The Need for Custom Servers:

Pre-built MCP servers cover popular services like GitHub, Slack, and databases. But every company has unique internal systems that no generic server covers. Your internal CRM, custom deployment pipeline, proprietary data warehouse, internal ticketing system - these need custom MCP servers.

Building a custom MCP server means your AI can interact with systems that are completely unique to your organization. It is like building a custom app for your business instead of using off-the-shelf software.

Real-World Analogy - Flipkart Seller Dashboard:

Flipkart provides standard tools for all sellers (listing, orders, payments). But a large seller like a clothing brand might build a custom integration that connects Flipkart to their internal inventory system, automatically updates stock levels, and generates custom reports. That custom integration is like a custom MCP server - purpose-built for their specific workflow.

When to Build vs. Use Pre-Built:

Server Components:

Every MCP server has four main parts:

• Transport Handler: Manages how messages flow (stdio or HTTP). The SDK handles this for you.
• Tool Definitions: Describe what tools are available, their parameters (JSON Schema), and what they do.
• Tool Handlers: The actual code that runs when a tool is called. Your business logic lives here.
• Error Handling: How the server responds when things go wrong. Critical for good LLM experience.

Available SDKs:

• TypeScript SDK (@modelcontextprotocol/sdk): Most popular, great for Node.js developers. Full support for all MCP features.
• Python SDK (mcp): Excellent for data science and ML teams. Async-first design.
• Kotlin SDK: For JVM-based applications and Android.
• C# SDK: For .NET applications and enterprise systems.

Project Structure (TypeScript):

my-mcp-server/
  package.json          // Dependencies: @modelcontextprotocol/sdk
  src/
    index.ts            // Server setup and transport
    tools/
      search-users.ts   // Tool: search users in CRM
      create-ticket.ts  // Tool: create support ticket
      get-metrics.ts    // Tool: fetch dashboard metrics
    utils/
      api-client.ts     // Internal API connection
      validators.ts     // Input validation helpers

Tool Descriptions Are Everything:

The LLM reads your tool descriptions to decide when to use each tool and what parameters to pass. A bad description means the LLM will misuse or ignore your tool. Think of it like writing documentation for a very smart but very literal intern.

Good vs Bad Tool Definitions:

Name: "get_data"
Description: "Gets data from the system"
Params: { id: string }

Name: "search_customers"
Description: "Search customers in the CRM by name, email,
  or phone number. Returns up to 10 matching customers
  with their name, email, subscription plan, and
  last active date. Use this when the user asks about
  a specific customer or wants to look someone up."
Params: {
  query: string (required) - "Search term: name, email, or phone"
  status: enum ["active", "inactive", "all"] - "Filter by status. Default: all"
}

Tool Design Principles:

• One Tool, One Job: search_customers, get_customer_details, update_customer - NOT manage_customers. Granular tools are easier for the LLM to use correctly.
• Descriptive Names: Use verb_noun format. search_logs, create_ticket, get_report. The name alone should hint at what it does.
• Typed Parameters: Use JSON Schema with types, enums, required fields, and descriptions for every parameter.
• Return Format: Return structured data, not raw dumps. Include only relevant fields. The LLM will present it to the user.
• Usage Hints: Tell the LLM WHEN to use this tool. "Use this when the user asks about order status" helps the LLM pick the right tool.

Input Validation - Trust Nothing:

The LLM generates the tool inputs. It can pass wrong types, missing fields, injection attempts, or completely unexpected values. Validate every single input as if it came from an untrusted user on the internet.

• Check required fields exist
• Validate types (string, number, enum values)
• Sanitize strings to prevent injection
• Enforce reasonable limits (max length, ranges)

Error Response Best Practices:

When something goes wrong, return errors that help the LLM recover:

// BAD: Cryptic error
{ "error": "404" }

// GOOD: Helpful error that guides the LLM
{
  "error": "Customer with ID cust_123 was not found.
  The customer may have been deleted.
  Try searching by email or name instead
  using the search_customers tool."
}

Security Checklist:

• Authentication: Verify the caller is authorized. For stdio, the OS process model handles this. For HTTP, implement proper auth (API keys, OAuth).
• Rate Limiting: Prevent the AI from making 1000 API calls in a loop. Set reasonable per-minute limits.
• Audit Logging: Log every tool call with timestamp, caller, parameters, and result. Essential for debugging and compliance.
• Timeouts: Set timeouts for external API calls. A hanging request should fail after a reasonable time, not block forever.
• Data Filtering: Never return sensitive data (passwords, API keys, PII) in tool results. Filter it out server-side.

Scenario:

Your company has an internal employee directory API. You want AI to help managers look up team members, check org charts, and find experts. Let us build an MCP server for this.

Step 1: Define Your Tools

Tool 1: search_employees
  Description: Search for employees by name, department,
    or skill. Returns matching employees with name, title,
    department, and email. Max 20 results.
  Params: { query: string, department?: string }

Tool 2: get_employee_profile
  Description: Get detailed profile of a specific employee
    including their team, manager, skills, location,
    and recent projects.
  Params: { employee_id: string }

Tool 3: get_org_chart
  Description: Get the organizational chart showing
    direct reports for a given manager.
  Params: { manager_id: string }

Tool 4: find_experts
  Description: Find employees with expertise in a
    specific technology or domain. Useful when user
    needs help finding the right person for a task.
  Params: { skill: string, location?: string }

Step 2: Implement Handlers

// Pseudocode for search_employees handler
function handle_search_employees(params):
  // 1. Validate inputs
  if params.query is empty: return error("Query is required")
  if params.query.length > 100: return error("Query too long")

  // 2. Call internal API
  results = call_employee_api("/search", params)

  // 3. Filter sensitive data
  remove salary, SSN, personal phone from results

  // 4. Format response
  return formatted_results with name, title, dept, email

Step 3: Configure and Test

// Add to Claude Desktop config
{
  "mcpServers": {
    "employee-directory": {
      "command": "node",
      "args": ["/path/to/your/server/dist/index.js"],
      "env": {
        "EMPLOYEE_API_URL": "https://internal-api.company.com",
        "API_KEY": "your-secret-key"
      }
    }
  }
}

// Test conversation:
User: "Who are the React experts in Bangalore?"
AI calls: find_experts({skill: "React", location: "Bangalore"})
AI: "Found 5 React experts in Bangalore: Priya (Staff Eng),
     Rahul (Senior Eng), ..."

Q: When should you build a custom MCP server vs using a pre-built one?

Q: What makes a good MCP tool description?

Q: Why should LLM-generated tool inputs be treated as untrusted?

Q: What is the recommended approach for MCP tool granularity?

Q: How should MCP server errors be structured?