Custom MCP Server: 5 Powerful Lessons From Building My Own

A custom MCP server connects your AI assistant directly to the tools you use every day. I built one to track time in Zoho Projects from Claude Code — and it changed how I work. Here are 5 powerful lessons from building a custom MCP server for real-world production use.

If you use AI coding assistants, you know the pain: you finish a task, then context-switch to a browser, open your project management tool, find the right project, fill in a form, and log your time. By the time you're done, your flow is gone. So I built a custom MCP server that handles it all in one sentence.

What Is a Custom MCP Server?

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. A custom MCP server is a lightweight TypeScript process that exposes specific tools — like "log time" or "create issue" — to your AI assistant.

Think of it as building a plugin. Instead of the AI only reading and writing files, a custom MCP server gives it hands. It can interact with any API, database, or service you connect.

Custom MCP Server Lesson 1: OAuth2 Self-Client Is Your Best Friend

Zoho's API uses OAuth2, which typically means redirect flows and browser-based auth. For a custom MCP server running locally, that's impractical.

Zoho's "self-client" option on the API console lets you generate tokens directly — no browser redirect needed. The catch: tokens expire, so your server must handle refresh tokens automatically. I store credentials in a .env file and refresh silently in the background.

This pattern works for most OAuth2 APIs. If your target service supports self-client or service account flows, use them.

Custom MCP Server Lesson 2: API Quirks Will Surprise You

Every API has undocumented behaviors. Zoho Projects had two that cost me hours:

• Time format mismatch: The API accepts times in 12-hour AM/PM format but returns them in 24-hour format. My custom MCP server converts between formats transparently.
• Empty list responses: When a bug list is empty, Zoho returns HTTP 204 (No Content) instead of an empty array. Without handling this, the server crashes.

These quirks are invisible in the docs. You only discover them in production. Budget extra time for API exploration when building a custom MCP server.

Custom MCP Server Lesson 3: Add Business Logic, Not Just CRUD

A basic custom MCP server wraps API endpoints — list projects, create tasks, log time. But the real value comes from encoding rules the AI can't figure out on its own.

My server includes conflict detection: before logging a time entry, it checks for overlapping entries. This prevents double-booking and catches mistakes before they hit the API.

Other examples of business logic worth adding to a custom MCP server:

• Default values (billable vs. non-billable based on project type)
• Input validation (reject future time slots)
• Data enrichment (look up project names from IDs automatically)

This is where a custom MCP server becomes more valuable than any generic API wrapper.

Custom MCP Server Lesson 4: Design Tools for the AI, Not for Humans

Human-facing APIs prioritize flexibility. AI-facing tools should prioritize clarity. When designing my custom MCP server tools, I learned three principles:

• Use descriptive names: log_time beats create_timelog_entry
• Add smart defaults: The AI shouldn't specify "Billable" every time
• Return structured data: Format output so the AI can summarize naturally

The best custom MCP server tools feel invisible — the AI uses them without the user knowing the implementation details.

Custom MCP Server Lesson 5: Start With 3 Tools, Not 30

My first instinct was to expose every Zoho Projects endpoint. I ended up with 14 tools, which works — but if I started over, I'd begin with three: list_projects, log_time, and list_issues.

Each tool in a custom MCP server needs proper error handling, input validation, and testing. Three solid tools are infinitely more useful than thirty brittle ones. Ship the minimum, then add tools when you actually need them.

The Result: My Daily Workflow Now

Before: Code → switch to browser → open Zoho → find project → fill form → log time → switch back → try to remember where I was.

After: "Log 45 minutes on issue #384, refactoring the authentication module." Done. One sentence, no context switch.

The custom MCP server handles project lookup, time calculation, and API formatting. What used to take 2–3 minutes of clicking now takes 5 seconds of typing. Over a week, that saves roughly 30–45 minutes of pure context-switching overhead.

Should You Build a Custom MCP Server?

Build one if:

• You use an AI assistant daily (Claude Code, Cursor, or similar)
• You frequently context-switch to a web app for repetitive actions
• That web app has a REST or GraphQL API
• You're comfortable with TypeScript or Python

Skip it if the tool already has an official MCP server, or if you only use it occasionally.

The code for my Zoho Projects custom MCP server is open source on GitHub. Star it if you find it useful, or use it as a template for your own integrations.

Frequently Asked Questions (FAQ)