From Curl to Context: Mastering MCP

📚 Overview

This educational demo teaches the Model Context Protocol (MCP) - a protocol for AI assistants to interact with external tools and data sources.

What You'll Learn

By working through this demo, you'll understand:

• ✅ MCP Protocol Basics - How tools are defined, listed, and called
• ✅ JSON-RPC 2.0 - Request/response format used by MCP
• ✅ Transport Methods - stdio (local) vs HTTP (remote) communication
• ✅ Error Handling - Proper error codes and messages
• ✅ TypeScript Development - Building and compiling MCP servers/clients
• ✅ Real-world Testing - Using curl, Postman, and programmatic clients

🎯 Contents

CURL_TO_CONTEXT/
├── README.md                          # This file - Full documentation
├── CHEATSHEET.md                      # Quick reference (print this!)
├── mcp-server/                        # Simple MCP Server Implementation
│   ├── src/
│   │   └── index.ts                   # Math operations MCP server
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-client-stdio/                  # Client using stdio transport
│   ├── src/
│   │   └── client.ts                  # stdio client implementation
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── mcp-client-remote/                 # Client using HTTP transport
│   ├── src/
│   │   └── client.ts                  # HTTP client implementation
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
└── examples/                          # JSON-RPC request examples
    ├── tools-list-request.json        # List all tools
    ├── add-request.json               # Addition example
    ├── subtract-request.json          # Subtraction example
    ├── multiply-request.json          # Multiplication example
    ├── divide-request.json            # Division example
    └── README.md                      # Usage guide

🚀 Quick Start

Prerequisites

Before starting, ensure you have Node.js 18+ installed:

node --version  # Should show v18.x.x or higher

If not installed, download from nodejs.org

💡 Tip: Print or bookmark CHEATSHEET.md for quick reference while working through the demo!

---

Option A: stdio Transport (Recommended First)

Best for: Learning local MCP communication

Step 1: Build the MCP Server

cd mcp-server
npm install
npm run build

What this does: Compiles the TypeScript server to JavaScript

Step 2: Run the stdio Client Demo

cd ../mcp-client-stdio
npm install
npm run build
npm start

Expected output:

• ✅ Server starts via stdio
• ✅ Lists 4 math tools (add, subtract, multiply, divide)
• ✅ Executes calculations automatically
• ✅ Demonstrates error handling

Duration: ~2 minutes

---

Option B: HTTP Transport (Remote Connection)

Best for: Understanding networked MCP servers

Terminal 1 - Start HTTP Server:

cd mcp-server
npm install       # If not already done
npm run build     # If not already done
npm run start:http

Expected output:

🚀 Starting MCP Math Server in HTTP mode
✅ HTTP Server running on http://localhost:5001

Keep this terminal running!

Terminal 2 - Run HTTP Client:

cd mcp-client-remote
npm install
npm run build
npm start

What you'll see:

• 📤 JSON-RPC requests
• 📥 Server responses
• ✅ Math operations over HTTP
• ✅ Error handling examples

Duration: ~3 minutes

---

Quick Manual Test (HTTP Server Running)

Try these curl commands to test the server directly:

List available tools:

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Calculate 10 + 5:

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"add","arguments":{"a":10,"b":5}},"id":2}'

Test error (divide by zero):

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"divide","arguments":{"a":10,"b":0}},"id":3}'

---

Troubleshooting

"Server not found" error?

# Make sure you built the server first:
cd mcp-server
npm run build

"Connection refused" error?

# Start the HTTP server in another terminal:
cd mcp-server
npm run start:http

Port 5001 already in use?

# Use a different port:
PORT=3000 npm run start:http
# Then update client:
MCP_SERVER_URL=http://localhost:3000/mcp npm start

📖 Key Concepts

JSON-RPC 2.0 Format

Every MCP message follows this structure:

{
  "jsonrpc": "2.0",        // Always "2.0"
  "method": "tools/call",   // MCP method name
  "params": {               // Optional parameters
    "name": "add",
    "arguments": {
      "a": 10,
      "b": 5
    }
  },
  "id": 1                   // Unique request ID
}

MCP Protocol Methods

Method	Purpose	When to Use
initialize	Handshake between client and server	First connection
tools/list	Discover available tools	Before calling tools
tools/call	Execute a specific tool	Perform operations
resources/list	Get available resources	Access data sources
prompts/list	Get available prompts	Template management
notifications/	Server-to-client updates	Real-time events

Error Codes (JSON-RPC 2.0)

Code	Name	Meaning
-32700	Parse error	Invalid JSON
-32600	Invalid Request	Malformed JSON-RPC
-32601	Method not found	Unknown method
-32602	Invalid params	Wrong parameters
-32603	Internal error	Server error

🎯 Quick Reference

Common Commands

List available tools:

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Call a tool:

curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"add","arguments":{"a":10,"b":5}},"id":2}'

Using example files:

cd examples
curl -X POST http://localhost:5001/mcp \
  -H "Content-Type: application/json" \
  -d @add-request.json

Project Commands

Command	Location	Purpose
npm install	Any directory	Install dependencies
npm run build	Any directory	Compile TypeScript
npm start	mcp-server	Run in stdio mode
npm run start:http	mcp-server	Run HTTP server
npm start	mcp-client-stdio	Run stdio demo
npm start	mcp-client-remote	Run HTTP demo
npm run dev	Any directory	Build + run
npm run watch	mcp-server	Auto-rebuild on changes

Environment Variables

# Change server port
PORT=3000 npm run start:http

# Change client server URL
MCP_SERVER_URL=http://localhost:3000/mcp npm start

📚 Learning Path

Immediate Next Steps

1. Review CHEATSHEET.md - Keep this handy for quick reference
2. Modify the examples - Change values in examples/*.json files and test
3. Add error handling - Try invalid inputs and see responses
4. Explore the code - Read through src/index.ts files to understand implementation

After Completing This Demo

1. Official MCP Documentation - modelcontextprotocol.io
2. Build Your Own Tools - Add new operations (modulo, power, square root)
3. Add Resources - Learn MCP resource management
4. Implement Prompts - Add prompt templates
5. Real Integration - Connect MCP to Claude, GPT, or other AI systems

🔗 Additional Resources

MCP Protocol & Specification

• Official MCP Documentation - modelcontextprotocol.io
  • Protocol specification, concepts, and best practices
• MCP GitHub Repository - github.com/modelcontextprotocol
  • Official SDKs, examples, and discussions
• MCP TypeScript SDK - npmjs.com/package/@modelcontextprotocol/sdk
  • The SDK used in this demo
• MCP Specification - spec.modelcontextprotocol.io
  • Detailed protocol specification

JSON-RPC 2.0

• JSON-RPC 2.0 Specification - jsonrpc.org/specification
  • Official spec for the protocol format MCP uses
• JSON-RPC Best Practices - jsonrpc.org/historical/json-rpc-over-http.html
  • Guidelines for JSON-RPC over HTTP

TypeScript & Node.js

• TypeScript Handbook - typescriptlang.org/docs/handbook
  • Learn TypeScript fundamentals
• Node.js Documentation - nodejs.org/docs
  • Official Node.js docs and guides
• Node.js Best Practices - github.com/goldbergyoni/nodebestpractices
  • Comprehensive Node.js best practices

Express.js (HTTP Server)

• Express.js Guide - expressjs.com/en/guide
  • Official Express.js documentation
• Express.js Best Practices - expressjs.com/en/advanced/best-practice-performance.html
  • Production best practices

Testing Tools

• curl Documentation - curl.se/docs
  • Command-line tool for testing HTTP endpoints
• Postman Learning - learning.postman.com
  • API testing and documentation platform
• HTTPie - httpie.io
  • User-friendly alternative to curl

AI & LLM Integration

• Anthropic Claude API - docs.anthropic.com
  • Integrate MCP with Claude
• OpenAI API - platform.openai.com/docs
  • Connect with GPT models
• LangChain - python.langchain.com
  • Framework for building LLM applications

Community & Examples

• Awesome MCP - Search for "awesome-mcp" on GitHub
  • Curated list of MCP resources and projects
• MCP Community Servers - github.com/modelcontextprotocol/servers
  • Official collection of MCP server implementations
• Discord/Slack Communities - Check MCP documentation for links
  • Get help and share your projects

Related Concepts

• Protocol Buffers - protobuf.dev
  • Alternative serialization format
• gRPC - grpc.io
  • Modern RPC framework
• GraphQL - graphql.org
  • Query language for APIs
• WebSockets - developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
  • Real-time bidirectional communication

Video Tutorials

• YouTube - MCP Tutorials - Search for "Model Context Protocol"
  • Video walkthroughs and explanations
• Anthropic's YouTube Channel - youtube.com/@AnthropicAI
  • Official videos about MCP and Claude

Books & Articles

• "Designing Data-Intensive Applications" by Martin Kleppmann
  • Understanding distributed systems and protocols
• "RESTful Web APIs" by Leonard Richardson & Mike Amundsen
  • API design principles
• MDN Web Docs - developer.mozilla.org
  • Web development reference

🤝 Contributing

This is an educational resource. Contributions welcome:

• Add more math operations (power, square root, etc.)
• Improve error messages and validation
• Add more detailed examples
• Create video tutorials or blog posts
• Translate documentation

📝 License

MIT License - Free for educational purposes

---

Questions or Issues? Open an issue or check the individual README files in each directory for more detailed information.