Building Custom MCP Servers: A Developer Guide

An MCP (Model Context Protocol) server is a lightweight application that exposes tools, data, and capabilities to AI models through a standardized protocol. Instead of an AI assistant directly calling your databases or SaaS APIs, it talks to an MCP server, which then handles the real integration work.

When an AI assistant needs to:

• Search your internal database
• Create a Jira ticket
• Query Salesforce or a legacy ERP

…it sends a structured request (via MCP) to the MCP server. The server validates the request, calls the underlying system, and returns a structured, AI-friendly response.

Compared to traditional APIs, MCP servers are designed specifically for AI consumption: they support automatic tool discovery, natural-language-to-structured input, richer error messages, and session-aware context.

Pre-built MCP servers already exist for popular tools like GitHub, Slack, and Google Drive. However, enterprises typically need custom MCP servers to connect AI to systems that are unique to their business:

• Internal databases: Product catalogs, customer data, proprietary analytics, operational metrics
• Custom business logic: Approval workflows, pricing engines, compliance checks, domain-specific rules
• Legacy systems: ERP, mainframes, proprietary on-prem APIs, systems without modern SDKs
• Composite tools: Unified tools that combine multiple data sources (e.g., CRM + billing + support) into a single intelligent interface

Custom MCP servers let you safely expose exactly the capabilities you want AI to use, with your own security, validation, and business rules baked in.

| Aspect | Traditional API | MCP Server |

|--------|-----------------|------------|

| Consumer | Human-written code | AI models |

| Discovery | API docs, Swagger, Postman | Automatic tool discovery via MCP protocol |

| Input | Strict, manually structured | Natural language → structured via tool schemas |

| Error handling | HTTP status codes, terse messages | AI-friendly, descriptive error messages |

| Context | Stateless per request | Session-aware, can maintain context across calls |

MCP servers are essentially APIs designed for AI, not for human developers. They describe tools in a way that models can understand and choose when to call, including descriptions, input schemas, and output formats.

Prerequisites

• Node.js 18+ or Python 3.10+ (both have official MCP SDKs)
• Understanding of the target system (database, SaaS, internal API)
• API credentials or access details for that system

TypeScript Setup

The official MCP TypeScript SDK is the fastest way to build servers.

Typical project structure:

• src/index.ts — Server entry point and tool registration
• src/tools/ — Individual tool implementations
• src/auth/ — Authentication handlers
• src/types/ — Shared type definitions for tool inputs/outputs

Key concepts:

• Server: Main MCP server instance that speaks the protocol
• Tool: A callable function with a name, description, and JSON Schema input
• Resource: A readable data source (files, DB records, documents)
• Transport: Communication channel (stdio for local, HTTP/SSE for remote)

Python Setup

The Python SDK mirrors the TypeScript approach with Pythonic patterns:

• Uses Pydantic models for input validation and typing
• Tool handlers are async functions
• Registration often uses FastAPI-style decorators for clarity

Both SDKs let you define tools, resources, and transports in a way that MCP-compatible clients (like Claude Desktop) can automatically discover and use.

Step 1: Define Your Tools

Start by deciding what you want the AI to do. For a customer database MCP server, you might define tools like:

• search_customers — Find customers by name, email, company, or segment
• get_customer_details — Return a full profile including order history
• get_customer_analytics — Revenue, LTV, churn risk, and other KPIs
• update_customer_notes — Append or edit notes on customer records

Each tool needs:

• Name: Short, descriptive, snake_case
• Description: Clear explanation; the AI uses this to decide when to call the tool
• Input schema: JSON Schema for required and optional parameters
• Output format: Structured JSON describing what the tool returns

Step 2: Implement Tool Handlers

Each tool handler is an async function that:

1. Validates input parameters
2. Calls the underlying API, database, or service
3. Formats the response for AI consumption
4. Handles errors gracefully

Best practices:

• Return structured JSON, not raw HTML or binary blobs
• Include context in responses, e.g.:
• "Found 15 customers matching 'Infosys', showing top 5 by revenue"
• Provide helpful error messages, e.g.:
• "No customers found matching 'Infosis'. Did you mean 'Infosys'?"
• Limit response size: Truncate large result sets and indicate that more data is available
• Cache frequently accessed data to reduce load on backend systems

Step 3: Add Authentication

MCP servers typically need two layers of auth:

1. Client authentication (who can call the MCP server)

• Local (stdio): Often trust the local user
• Remote (HTTP): Use OAuth 2.0, API keys, or JWT-based auth

2. Backend authentication (MCP server → target system)

• Store credentials securely (env vars, secret manager)
• Use service accounts with least-privilege permissions
• Rotate keys and tokens regularly

Step 4: Test Locally

You can test your MCP server with Claude Desktop:

1. Add the server configuration to Claude Desktop's config
2. Start a conversation and confirm Claude discovers your tools
3. Call each tool with different inputs
4. Verify error handling for invalid inputs and backend failures

Step 5: Deploy for Production

Common deployment options:

• Local process (stdio): Runs alongside Claude Desktop; ideal for personal or dev use
• Docker container (HTTP/SSE): Deploy on your own infra; good for teams and enterprises
• Serverless (AWS Lambda, GCP Functions): Auto-scaling, pay-per-use; good for spiky workloads
• Kubernetes: For large-scale, multi-tenant, or multi-server deployments

In production, you’ll also want proper logging, monitoring, and security hardening.

Multi-Tool Composition

You can build MCP servers that orchestrate multiple backend systems and present them as a single intelligent toolset.

Example: Sales Intelligence Server

• Pulls deal data from Salesforce
• Enriches company info from Clearbit/ZoomInfo
• Checks engagement history from HubSpot
• Returns a unified view, e.g.:
• "TCS has a Rs 45L deal in Stage 3, last engaged 5 days ago, company revenue grew 12% YoY"

The AI sees a single set of tools, while the MCP server handles all cross-system logic.

Streaming Responses

For long-running or large operations, MCP supports streaming:

• Real-time progress for database migrations
• Live log streaming for deployment pipelines
• Incremental results for large search queries

Streaming keeps the AI informed and responsive instead of waiting for a single large response.

Caching and Performance

To keep MCP servers fast and reliable:

• Response caching: Cache tool results for common queries with TTL
• Connection pooling: Reuse DB or API connections instead of reconnecting each time
• Batch operations: Combine multiple similar requests into a single backend call
• Circuit breakers: Detect backend overload and fail gracefully with clear messages

Error Handling Patterns

AI-friendly error handling is critical:

• Retryable errors: Mark errors as retryable so the AI knows it can safely try again
• Suggestion errors: e.g. "Permission denied for 'delete_customer'. You have read-only access. Contact admin for write permissions."
• Partial results: If one of several backend calls fails, return what you have plus a note about the failure
• Timeout handling: Use reasonable timeouts and return partial or summarized results instead of hanging

Security

• Store all credentials in environment variables or a secret manager
• Validate all tool inputs against schemas
• Apply rate limiting per user and per tool
• Maintain audit logs for compliance and investigations
• Run regular security reviews and penetration tests

Monitoring

Track and alert on:

• Tool call latency (P50, P95, P99)
• Error rates by tool and error type
• Usage patterns (which tools, which users, peak times)
• Backend API and database health
• Anomalies (sudden error spikes, unusual access patterns)

Documentation

Provide:

• Tool descriptions optimized for AI understanding
• Input/output examples for each tool
• Error code and error pattern references
• Deployment and configuration guides
• Runbooks for common operational issues

Boolean & Beyond specializes in building custom MCP servers for enterprises in Bangalore and Coimbatore.

We focus on connecting AI to the systems that matter most to Indian enterprises:

• Internal databases and analytics platforms
• Legacy ERP systems and mainframes
• SAP, Tally, custom CRM systems
• Internal tools and proprietary APIs without off-the-shelf connectors

Our MCP servers are built for production:

• Strong authentication and authorization
• Robust error handling and AI-friendly messages
• Monitoring, logging, and alerting
• Performance optimizations (caching, batching, pooling)

If you need AI to safely and intelligently work with your internal systems—whether that’s updating records, running analytics, or orchestrating workflows—Boolean & Beyond can design and implement the MCP servers to make it happen.

Explore more from our AI solutions library:

• LLM Integration & API Optimization — Connect ChatGPT, Claude, and GPT-4 APIs to your existing applications with best practices for cost and latency.
• Document Ingestion Pipeline for Enterprise Knowledge Bases — Build the document processing pipeline that feeds your enterprise AI copilot with structured knowledge.