MCP Demo Project

Overview

This project demonstrates how to build and test a Model Context Protocol (MCP) server using Python and FastMCP.

The repository contains:

• server.py - MCP Server implemented using FastMCP
• server.js - Sample REST API implemented using Express.js
• client_test.py - Python client for testing the MCP server
• requirements.txt - Python dependencies
• package.json - Node.js dependencies (optional)

---

Architecture

+----------------------+
| MCP Client           |
| (Claude, Cursor,     |
|  Custom Client)      |
+----------+-----------+
           |
           | MCP Protocol
           |
           v
+----------------------+
| server.py            |
| FastMCP Server       |
+----------+-----------+
           |
           | HTTP (Optional)
           |
           v
+----------------------+
| server.js            |
| Express REST API     |
+----------+-----------+
           |
           v
+----------------------+
| Database / Services  |
+----------------------+

The MCP server exposes tools, resources, and prompts that AI agents can use.

The Express server demonstrates how an MCP server can interact with existing REST APIs.

---

Services

1. Python MCP Server (server.py)

The MCP server runs on:

http://127.0.0.1:8000/mcp

Available Tools

add_numbers

Adds two integers.

Example:

{
  "a": 5,
  "b": 7
}

Result:

12

---

get_weather

Returns mock weather information.

Example:

{
  "city": "Hyderabad"
}

Result:

The weather in Hyderabad is sunny, 25°C.

---

Available Resources

greeting://{name}

Example:

greeting://Jaya

Result:

Hello, Jaya! Welcome to MCP.

---

Available Prompts

code_review_prompt

Generates a code review prompt.

Input:

public class Test {}

Output:

Please review this code and suggest improvements:

public class Test {}

---

2. Node.js REST Server (server.js)

The Express server runs on:

http://localhost:3000

Endpoints

Health Check

GET /health

Example Response:

{
  "status": "ok",
  "uptime": 123.45
}

---

Manifest

GET /manifest

Returns server metadata.

---

Context API

POST /context

Request:

{
  "query": "Hello MCP",
  "metadata": {
    "user": "Jaya"
  }
}

Response:

{
  "received": {
    "query": "Hello MCP",
    "metadata": {
      "user": "Jaya"
    }
  },
  "response": "MCP server received: Hello MCP"
}

---

Prerequisites

Python

Verify installation:

python --version

Install dependencies:

pip install -r requirements.txt

---

Node.js (Optional)

Verify installation:

node -v
npm -v

Install dependencies:

npm install

or

npm install express

---

Running the Application

Start the MCP Server

python server.py

Expected Output:

Uvicorn running on http://127.0.0.1:8000

---

Start the Express Server

node server.js

Expected Output:

MCP server listening on http://localhost:3000

---

Testing the MCP Server

Step 1: Initialize Session

Windows CMD:

curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}"

Copy the returned:

mcp-session-id

---

Step 2: List Available Tools

curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "Mcp-Session-Id: <SESSION_ID>" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"2\",\"method\":\"tools/list\"}"

---

Step 3: Call add_numbers Tool

curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "Mcp-Session-Id: <SESSION_ID>" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"3\",\"method\":\"tools/call\",\"params\":{\"name\":\"add_numbers\",\"arguments\":{\"a\":5,\"b\":7}}}"

Expected Result:

12

---

Step 4: Call get_weather Tool

curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "Mcp-Session-Id: <SESSION_ID>" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"4\",\"method\":\"tools/call\",\"params\":{\"name\":\"get_weather\",\"arguments\":{\"city\":\"Hyderabad\"}}}"

---

Testing the Express Server

Health Check:

curl http://localhost:3000/health

Manifest:

curl http://localhost:3000/manifest

Context API:

curl -X POST http://localhost:3000/context -H "Content-Type: application/json" -d "{\"query\":\"Hello MCP\"}"

---

MCP Concepts Used

Tool

An executable function exposed to MCP clients.

Examples:

• add_numbers
• get_weather

Resource

Read-only contextual information.

Example:

• greeting://{name}

Prompt

Reusable prompt templates exposed to AI clients.

Example:

• code_review_prompt

---

Learning Objectives

This project demonstrates:

• Building an MCP Server with FastMCP
• Exposing Tools, Resources, and Prompts
• Using Streamable HTTP Transport
• Testing MCP APIs with curl
• Creating a REST API with Express.js
• Integrating MCP with existing backend services
• Understanding MCP architecture and workflows