How to build your own MCP server?

Anthropic has released Model Context Protocol, a new standard for connecting AI system with external system. The external system could be any data sources like web, local DB, or other tools where data exists. MCP (Model Context Protocol) addresses the challenge of isolating AI models from data and connecting them effectively across diverse information sources and systems.

In this blog, we will explore MCP and how to build a custom MCP server. Here's what we'll cover:

MCP Introduction:

• What is MCP?

• Why MCP?

• MCP Architecture

• MCP Servers

• MCP Server’s Core Concepts

Integrating Pre-built MCP Servers to Claude

1. Adding Filesystem MCP Server to Claude

• Prerequisites

• Configuring Filesystem MCP Server

• Testing Filesystem MCP Server

2. Adding GitHub MCP Server to Claude

• Prerequisites

• Configuring GitHub MCP Server

• Testing GitHub MCP Server

Building Custom MCP Server

• Prerequisites

• Build Gmail, GCalendar MCP Server

• Claude Desktop Configuration changes

• Test Gmail, GCalendar MCP Server

• Troubleshooting steps for common challenges

---

MCP Introduction:

What is MCP?

MCP is an open-source protocol that standardize how external applications provide context to LLMs. In simple it provides seamless integration between LLM and external tools.

Why MCP?

• It provides instant and easy integration between LLM and external tool.

• Freedom to switch between LLM providers.

• Secure data handling within infrastructure.

MCP Architecture:

MCP follows a client-server architecture.

Source:- MCP Architecture

Let us see the components of MCP architecture.

Host with MCP Client:
These act as connectors, creating one-to-one communication links between the host and the MCP servers. One MCP host can have multiple client instances.

MCP Servers: - [This blog is all about MCP Servers]
Main code that performs specific tasks or functions. They use the Model Context Protocol to expose particular features or capabilities.

Local Data Sources:
Files, databases and services on your local machine that MCP can securely access.

Remote Services:
External APIs, services, tools and platforms that MCP connects with to fetch or push data.

MCP message types:
MCP defines three message types -Requests, Responses, and Notifications.

MCP messages:- Request, Response, Notifications

Requests:

Client Request: User-initiated actions from client to server. Ex:- get_email()

Server Request: Server asking client for LLM assistance using sampling.

Response:

When one party makes a request, the other must respond with either success results or error status.

Notifications:

Status changes, Resource updates can be shared between client and server through notifications.

MCP Servers:

Pre-built MCP servers are available for major platforms like GitHub, Cloudflare, and Slack, with more being added through Community, Third-Party contributions. While our diagram shows some sample servers, it's just a snapshot - check out the complete MCP server list here.

MCP Server’s core features:

1. Resources:

Resources are Data/context providers for LLMs, they are like GET endpoints, no computation involved.

@mcp.resource("items://{item_id}")
def get_item(item_id: str) -> str:
    return f"Item ID: {item_id}"

2. Tools:

Tools perform computations, and actions, and cause changes, unlike resources which simply return data. Kind of Post method in Rest API.

@mcp.tool()
def add_numbers(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

3. Prompts:

Reusable templates that guide LLM interactions.

@mcp.prompt()
def review_code(code: str) -> str:
    return f"Please review this code:\n\n{code}"

Now that we have explored the fundamentals of MCP, let us see how it is implemented in practice by adding a pre-built MCP server to Claude Desktop.

Adding Pre-built Filesystem MCP Server to Claude:

With many MCP servers already available for various tools, integrating them with Claude is an easy process.

1. Prerequisites:

a) Install Claude Desktop App:

Download and Install Claude Desktop App from here.

b) Check if Node.js is Installed on Your System:

Open the command line:

• On macOS, open the Terminal from your Applications folder

• On Windows, press Windows + R, type “cmd”, and press Enter

Execute below command and see if Node.js installed

node --version

Could not find Node.js? Download it from nodejs.org and install it.

Tip: Install NodeJS using Node Version Manager.

2. Configuring Filesystem MCP Server

a) Locate claude_desktop.config File:

In the Desktop App, go to settings

In Settings pane, go to the Developer Tab, where you can see “Edit Config”

Clicking this “Edit Config” will take you to the configuration file location

macOS:

~/Library/ApplicationSupport/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

b) Replace the content of claude_desktop_config.json file:

Open the claude_desktop_config.json and add MCP server configuration.

1. Choose the MCP server (For example, we have chosen Filesystem MCP server).

2. Open the claude_desktop_config.json

3. Copy the Filesystem MCP server config and place it in the claude_desktop_config.json.

Here’s the config of the Filesystem MCP server.

Replace "username" with your computer's username and add any folders you want Claude to access.

The same approach works for adding other pre-built MCP servers (Reference, Community, Third-Party Servers).

c) Restart Claude

Now restart Claude to pick up the MCP server configuration.

Do you see a hammer and plug icon like below? It shows your Claude has picked up the MCP server configuration. Click the icon to view the attached MCP servers.

Also check the settings, to ensure it is properly integrated without issues.

Not seeing hammer symbol? Check here for troubleshooting steps.

3. Test Filesystem MCP server

Now let us test the Filesystem MCP server that we attached to Claude.

I asked Claude to list directories, search for files, and even create a Next.js project by setting up the required directories and files.

Note: - However, deletion of files or directories is not possible with the Filesystem MCP server.

Below are the actions that can be performed by the filesystem MCP server.

Learn More about the Filesystem MCP server here.

Let's also include a prebuilt GitHub MCP Server.

Adding Pre-built GitHub MCP Server to Claude:

1. Prerequisites:

As mentioned in the previous section, ensure you have Claude Desktop App and Node.js installed.

2. Configuring GitHub MCP Server

Add GitHub MCP server configuration to claude_desktop_config.json.

Below is my current configuration, which includes both the filesystem and GitHub MCP servers.

Get your GitHub Personal Token and add in the config.

{
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "C:/Users/Test/Desktop",
          "C:/Users/Test/Downloads"
        ]
      },
      "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "XXXX"
      }
    }
    }
  }

After restarting Claude Desktop, click the plug symbol and you can now see GitHub MCP server is now added along with filesystem MCP server

Now let us test the attached GitHub MCP server

3. Test GitHub MCP server

Claude + GitHub MCP is turning into an AI coding assistant. With just a few simple prompts and clicks, it can build a codebase in seconds, push it to the repo, and get it ready for deployment. While it still needs some human inputs, it makes the whole process much easier and faster.

Find more about GitHub MCP server.

Building custom MCP Server:

We have integrated the pre-built MCP servers. Now, let’s try building one of our own. You can build MCP Server or Client, using any one of following SDKs.

TypeScript SDK

Python SDK.

Kotlin SDK

Let us do with Python SDK.

1. Prerequisites:

a) Install mcp package:

There are two ways to install the MCP package for building servers:

Using pip:

pip install mcp

It is recommended to use uv. (a faster Rust-based Python package manager):

uv add "mcp[cli]"

b) Set up OAuth 2.0 for Gmail and Calendar API access:

• Follow the OAuth 2.0 configuration guide and setting up OAuth consent with API scope of Gmail and Calendar.

• Download credentials.json.

• On first run, our code creates token.pickle for storing your authenticated session.

2. Build Gmail, GCalendar MCP Server

Let’s build Gmail + Google calendar MCP server using python SDK.

a) Import mcp package

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("gmail_mcp_server")

b) Define Gmail Functions in server.py

We are going to implement three Gmail functionalities:

• Get latest emails

• Search specific email

• Get email content

@mcp.resource("gmail://inbox") 
def get_emails() -> str:
    """Get recent emails from inbox"""
    try:
        service = get_gmail_service()
        results = service.users().messages().list(
            userId='me', 
            maxResults=10
        ).execute()
        
        messages = []
        for msg in results.get('messages', []):
            email = service.users().messages().get(
                userId='me',
                id=msg['id']
            ).execute()
            headers = email['payload']['headers']
            subject = next((h['value'] for h in headers if h['name'] == 'Subject'), 'No Subject')
            sender = next((h['value'] for h in headers if h['name'] == 'From'), 'Unknown')
            messages.append(f"From: {sender}\nSubject: {subject}\n---")
            
        return "\n".join(messages) if messages else "No messages found"
        
    except Exception as e:
        logger.error(f"Get emails failed: {e}")
        return str(e)

get_emails() - function uses @mcp.resource("gmail://inbox") to return recent emails.

get_email_content() and send_email() use @mcp.tool() to perform actions and return the response.

c) Define GCalendar Functions

We are going to implement two GCalendar functionalities:

• Search events

• Create new calendar event

@mcp.tool()
def create_event(summary: str, start_time: str, end_time: str, description: str = "") -> dict:
    try:
        calendar = get_calendar_service()
        event = {
            'summary': summary,
            'description': description,
            'start': {'dateTime': start_time, 'timeZone': 'UTC'},
            'end': {'dateTime': end_time, 'timeZone': 'UTC'}
        }
        
        event = calendar.events().insert(calendarId='primary', body=event).execute()
        return {"result": f"Event created: {event.get('htmlLink')}"}
    except Exception as e:
        return {"error": str(e)}

list_events() use @mcp.resource("calendar://events/{max_results}") to return the events scheduled and create_event() use @mcp.tool() to create a new calendar event.

The above are just code snippets to demonstrate the concepts.

For a full working code, check out the repo here.

3. Claude Desktop Configuration:

Run below command to add the server (server.py- our python file where we defined all functionalities) to claude_desktop_config.json.

mcp install server.py 

Note: After using mcp install server.py, always double-check the auto-generated entries in claude_desktop_config.json, as they may be incorrect at sometimes.

The claude_desktop_config.json should be something like below.

"gmail_mcp_server": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/xxx/Documents/github/mcp_server",
        "run",
        "server.py"
      ]
    }

4. Test Gmail+GoogleCalender MCP Server:

5. Troubleshooting steps for common challenges

Issue:

npm error enoent ENOENT: no such file or directory, lstat 'C:\Users\XXXX\AppData\Local\AnthropicClaude\app-0.7.8\${APPDATA}'

Solution: Uninstall Node.js and install it using Node Version Manager.

Issue:

Error: spawn uv ENOENT

Solution: Install uv.

Issue:

This error occurred while trying to integrate a custom MCP server with Claude.

Error in MCP connection to server gmail_mcp_server: SyntaxError: Unexpected token 'E', "Error: typ"... is not valid JSON

Solution: Verify that the claude_desktop_config.json entries are correctly configured also verify your code for any syntax error.

Check logs to find the issue in detail.

macos:- ~/Library/ApplicationSupport/Claude/logs

windows:- %APPDATA%\Claude\logs

After seeing more about MCP servers, let us explore the clients that support MCP servers.

MCP Supported Clients:

In addition to Claude, other clients also support MCP, but they have certain limitations in terms of the server’s features. Only a few clients offer full support for all three features—resources, prompts, and tools.

source:- Example Clients - Model Context Protocol

Want to build MCP Client? check here.

Learn More:

We've covered MCP fundamentals, explored pre-built servers, and learned how to build our own.

Ready to create your own MCP server? Let LLMs help you build it!

• Share the MCP documentation (llms.txt) with your preferred LLM (Claude, ChatGPT)

• Go to Python SDK or TypeScript SDK and collect the README files and other relevant documentation.

• Provide the SDK documents to your LLM along with llms.txt.

• Now Describe your server requirements clearly, for example:

Build an MCP server that:
- Connects to PostgreSQL database
- Exposes table schemas as resources
- Provides tools for running read-only SQL queries
- Includes prompts for common data analysis tasks

That's it! Get your code from the LLM, set it up, and start using your custom MCP server in Claude Desktop.

Happy building!