Forem: Tamoghna

Build Your Own AI Agent with MCP: A Developer's Guide to Model Context Protocol

Tamoghna — Mon, 04 Aug 2025 17:37:50 +0000

Build Your Own AI Agent with MCP: A Developer's Guide to Model Context Protocol

Ever wondered how to give your AI assistant access to real-time data, databases, or custom tools? The Model Context Protocol (MCP) is your gateway to building truly intelligent agents that can interact with the world beyond their training data.

What is MCP and Why Should You Care?

If you've been working with AI assistants like Claude, ChatGPT, or local models, you've probably hit the same wall I did: they're incredibly smart, but completely isolated from your actual data and tools.

Imagine if your AI could:

Query your database in real-time
Read from your knowledge base
Execute custom business logic
Access live APIs and services

That's exactly what the Model Context Protocol (MCP) enables. Think of it as a standardized way for AI models to communicate with external tools and data sources, similar to how REST APIs work for web services.

MCP was developed by Anthropic and is quickly becoming the standard for AI-tool integration. Instead of cramming everything into prompts or fine-tuning models, you can build specialized servers that your AI can call upon when needed.

The Architecture: Servers, Clients, and Protocols

Before we dive into code, let's understand the key components:

🖥️ MCP Server

Your custom server that provides tools and data to AI models. It's like a waiter that knows exactly what's available and how to get it.

🤖 MCP Client

The bridge between your AI model (OpenAI, Claude, etc.) and your MCP server. It translates between AI function calls and MCP protocol.

📡 Transport Protocols

MCP supports multiple ways for clients and servers to communicate:

stdio (Standard Input/Output): Great for local development and simple setups
SSE (Server-Sent Events): Perfect for web applications and real-time updates
HTTP: For traditional request-response patterns

For this tutorial, we'll focus on stdio since it's the most straightforward to get started with.

Building Your First MCP Server

Let's build a knowledge base server that can answer questions from a structured dataset. Here's the complete server implementation:

#!/usr/bin/env python3
import asyncio
import json
import os
from mcp.server import Server
import mcp.server.stdio
import mcp.types as types

# Create server instance
server = Server("knowledge-base-server")

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    """Define what tools your server provides"""
    return [
        types.Tool(
            name="get_knowledge_base",
            description="Retrieve information from the knowledge base",
            inputSchema={
                "type": "object",
                "properties": {},
                "required": [],
            },
        ),
    ]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict | None):
    """Handle tool execution requests"""
    if name == "get_knowledge_base":
        try:
            kb_path = os.path.join("data", "kb.json")

            with open(kb_path, 'r') as kb_file:
                kb_data = json.load(kb_file)

                # Format the knowledge base nicely
                kb_text = "Knowledge Base Contents:\n\n"
                for i, item in enumerate(kb_data, 1):
                    question = item.get("question", "Unknown")
                    answer = item.get("answer", "Unknown")
                    kb_text += f"Q{i}: {question}\n"
                    kb_text += f"A{i}: {answer}\n\n"

                return [types.TextContent(type="text", text=kb_text)]

        except Exception as e:
            return [types.TextContent(
                type="text", 
                text=f"Error accessing knowledge base: {str(e)}"
            )]
    else:
        raise ValueError(f"Unknown tool: {name}")

async def main():
    """Run the server using stdio transport"""
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream)

if __name__ == "__main__":
    asyncio.run(main())

Sample Knowledge Base (`data/kb.json`)

[
  {
    "question": "What is MCP?",
    "answer": "MCP (Model Context Protocol) is a protocol for AI assistants to communicate with external data sources and tools."
  },
  {
    "question": "What transport protocols are supported?",
    "answer": "MCP supports stdio, SSE (Server-Sent Events), and HTTP transport protocols."
  },
  {
    "question": "What is the default transport protocol for MCP?",
    "answer": "The default transport protocol for MCP is stdio (standard input/output)."
  }
]

Creating the MCP Client

Now let's build a client that connects your AI model to the MCP server:

import asyncio
import json
from contextlib import AsyncExitStack
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from openai import AsyncOpenAI

class MCPOpenAIClient:
    def __init__(self, model="gpt-4o"):
        self.session = None
        self.exit_stack = AsyncExitStack()
        self.model = model
        self.openai_client = AsyncOpenAI()

    async def connect_to_server(self, server_script_path="server.py"):
        """Connect to the MCP server"""
        server_params = StdioServerParameters(
            command="python",
            args=[server_script_path],
        )

        # Establish connection
        stdio_transport = await self.exit_stack.enter_async_context(
            stdio_client(server_params)
        )
        stdio, write = stdio_transport

        self.session = await self.exit_stack.enter_async_context(
            ClientSession(stdio, write)
        )

        await self.session.initialize()
        print("✅ Connected to MCP server!")

    async def get_mcp_tools(self):
        """Convert MCP tools to OpenAI function format"""
        tools_result = await self.session.list_tools()
        return [
            {
                "type": "function",
                "function": {
                    "name": tool.name,
                    "description": tool.description,
                    "parameters": tool.inputSchema,
                },
            }
            for tool in tools_result.tools
        ]

    async def process_query(self, query: str) -> str:
        """Process a query using AI + MCP tools"""
        tools = await self.get_mcp_tools()

        # First AI call with tools available
        response = await self.openai_client.chat.completions.create(
            model=self.model,
            messages=[
                {"role": "system", "content": "You have access to a knowledge base. Use it to answer questions accurately."},
                {"role": "user", "content": query}
            ],
            tools=tools,
            tool_choice="auto",
        )

        assistant_message = response.choices[0].message

        # Handle tool calls
        if assistant_message.tool_calls:
            messages = [
                {"role": "user", "content": query},
                assistant_message,
            ]

            # Execute each tool call
            for tool_call in assistant_message.tool_calls:
                result = await self.session.call_tool(
                    tool_call.function.name,
                    arguments=json.loads(tool_call.function.arguments),
                )

                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result.content[0].text,
                })

            # Get final response with tool results
            final_response = await self.openai_client.chat.completions.create(
                model=self.model,
                messages=messages,
            )

            return final_response.choices[0].message.content

        return assistant_message.content

Putting It All Together

Here's how to use your new AI agent:

async def main():
    client = MCPOpenAIClient()

    try:
        # Connect to your MCP server
        await client.connect_to_server("server.py")

        # Test queries
        queries = [
            "What is MCP?",
            "What transport protocols are supported?",
            "How does this knowledge base work?"
        ]

        for query in queries:
            print(f"\n🤔 Question: {query}")
            response = await client.process_query(query)
            print(f"🤖 Answer: {response}")

    finally:
        await client.cleanup()

if __name__ == "__main__":
    asyncio.run(main())

Understanding Transport Protocols

stdio (What We Used)

Pros: Simple, great for development, works locally
Cons: Not suitable for web applications
Use case: Local AI agents, development, CLI tools

# Server runs as a subprocess, communicates via stdin/stdout
server_params = StdioServerParameters(
    command="python",
    args=["server.py"],
)

SSE (Server-Sent Events)

Pros: Web-friendly, real-time updates, HTTP-based
Cons: More complex setup
Use case: Web applications, dashboards, real-time systems

# Server runs as web service, client connects via HTTP
server_params = SSEServerParameters(
    url="http://localhost:8000/sse",
)

Why This Approach is Powerful

Traditional AI integration often looks like this:

Fetch data in your application
Stuff it into prompts
Send to AI
Parse response
Hope for the best

With MCP, your workflow becomes:

AI identifies what information it needs
AI calls appropriate tools via MCP
MCP server provides fresh, structured data
AI processes and responds

This means:

✅ Always fresh data (no stale embeddings)
✅ Structured interactions (no prompt injection)
✅ Scalable architecture (add tools without retraining)
✅ Reusable components (one server, many AI clients)

Tips and Gotchas

🎯 Best Practices

Start Simple: Begin with stdio transport and basic tools
Error Handling: Always wrap MCP calls in try-catch blocks
Tool Design: Make tools focused and well-documented
Resource Cleanup: Always clean up connections properly

⚠️ Common Pitfalls

Blocking Operations: Use async/await throughout your server
Large Payloads: MCP isn't meant for transferring huge datasets
Security: Validate all inputs in your tool handlers
Connection Management: Handle disconnections gracefully

# Good: Proper error handling
try:
    result = await self.session.call_tool(tool_name, args)
    return result.content[0].text
except Exception as e:
    return f"Tool error: {str(e)}"

# Bad: No error handling
result = await self.session.call_tool(tool_name, args)
return result.content[0].text

Project Structure for Success

Here's how I organize my MCP projects:

my-mcp-agent/
├── server.py              # MCP server implementation
├── client.py              # AI client with MCP integration
├── data/
│   ├── kb.json           # Knowledge base
│   └── config.yaml       # Server configuration
├── tools/
│   ├── __init__.py
│   ├── knowledge_base.py # Tool implementations
│   └── calculator.py     # More tools
├── requirements.txt       # Dependencies
├── .env                  # API keys (don't commit!)
└── README.md             # Documentation

Going Further: Advanced Ideas

Once you've mastered the basics, consider these extensions:

🔄 Multi-Tool Servers

@server.list_tools()
async def handle_list_tools():
    return [
        types.Tool(name="search_database", ...),
        types.Tool(name="send_email", ...),
        types.Tool(name="generate_report", ...),
    ]

🌐 Web-Based Agents

Switch to SSE transport for browser-based AI agents:

# Instead of stdio, use SSE for web apps
from mcp.client.sse import sse_client

async with sse_client(sse_params) as transport:
    # Your web-based AI agent

🔗 Tool Chaining

Let your AI call multiple tools in sequence:

# AI can call get_user_data, then send_notification, then log_action
# All in one conversation turn!

Essential Resources

MCP Specification: The official spec
Python SDK: Official Python implementation
MCP Servers Repository: Community examples
Claude Desktop Integration: Use MCP with Claude directly

Wrapping Up

MCP represents a fundamental shift in how we build AI applications. Instead of cramming everything into prompts or fine-tuning models, we can build modular, reusable tools that any AI can leverage.

The knowledge base server we built today is just the beginning. Imagine servers that:

Query your databases in real-time
Interact with APIs and web services
Execute business logic and workflows
Provide specialized domain knowledge

The possibilities are endless, and the barrier to entry has never been lower.

What will you build with MCP? Drop a comment below with your ideas – I'd love to see what the community creates!

Connect & Explore More

If you found this tutorial helpful, I'd love to connect! Here are some ways to continue the conversation:

🔗 Connect with me:

LinkedIn - Let's discuss AI development and collaboration opportunities
GitHub - Check out more AI projects and contribute to open source

📚 Explore the project:

Complete MCP Knowledge Base Server - Fork the full project from this tutorial
MCP Official Repository - Don't forget to star the official MCP project!

What will you build with MCP? Drop a comment below with your ideas – I'd love to see what the community creates and help troubleshoot any challenges you encounter!

Follow me here on Dev.to for more tutorials on AI agents, developer tools, and cutting-edge tech. More MCP content coming soon! 🚀

A Beginner's Guide to Worker Threads in Node.js: Unlocking Multithreading for Enhanced Performance

Tamoghna — Thu, 05 Dec 2024 15:58:30 +0000

Introduction to Worker Threads in Node.js

Node.js has long been known for its single-threaded, event-driven nature, which is great for I/O-heavy applications but can struggle with CPU-bound tasks. With the release of Worker Threads in Node.js 10.5, developers gained the power to execute CPU-intensive operations on parallel threads, effectively improving application performance.

In this article, we’ll explore what Worker Threads are, how they work, and provide examples to help you understand and use them in your Node.js applications.

What are Worker Threads in Node.js?

Worker Threads are a module in Node.js that allows you to create multiple threads within a single Node.js process. Unlike the main thread, which is single-threaded, Worker Threads allow for concurrency, meaning that tasks can run in parallel without blocking the main event loop.

This makes Worker Threads particularly useful for tasks that require significant CPU resources, such as data processing, machine learning, image manipulation, and other computation-heavy operations.

When to Use Worker Threads

Worker Threads aren’t always necessary for Node.js applications, but they can be valuable in specific situations:

CPU-bound tasks: If your application performs intensive calculations (e.g., processing large datasets or encoding media files), Worker Threads can prevent these tasks from blocking the main thread.
Parallel processing: Tasks that can run independently, like handling separate data sources, can benefit from being executed in parallel.
Multithreaded applications: If your Node.js application needs to run multiple threads by design (e.g., for concurrent computations or background processing), Worker Threads offer an efficient way to manage this.

Getting Started with Worker Threads

Worker Threads are part of the worker_threads module in Node.js, so there’s no need for any external packages. Here’s a simple example to illustrate how to use them.

Basic Example of Worker Threads

Let’s create a basic example where a Worker Thread calculates the sum of numbers from 1 to a specified limit.

Install Node.js version 12 or later to ensure compatibility with Worker Threads.

Create a new file called worker.js with the following content:

// worker.js
const { parentPort, workerData } = require('worker_threads');

function calculateSum(limit) {
 let sum = 0;
 for (let i = 1; i <= limit; i++) {
   sum += i;
 }
 return sum;
}

   // Send the result back to the main thread
   parentPort.postMessage(calculateSum(workerData.limit));

Create a main script file (e.g., index.js) to start the Worker Thread:

// index.js
const { Worker } = require('worker_threads');

function runWorker(limit) {
      return new Promise((resolve, reject) => {
        const worker = new Worker('./worker.js', {
          workerData: { limit },
        });

        worker.on('message', resolve); // receive result from worker
        worker.on('error', reject);
        worker.on('exit', (code) => {
          if (code !== 0)
            reject(new Error(`Worker stopped with exit code ${code}`));
        });
    });
}

// Run the Worker with a limit of 1,000,000
runWorker(1000000)
  .then((result) => console.log(`Result: ${result}`))
  .catch((err) => console.error(err));

In this example, index.js initiates a new Worker with a limit of 1,000,000, and worker.js performs the calculation. The main thread remains free, allowing it to handle other tasks while the Worker processes the calculation.

Communicating Between Threads

Communication between the main thread and Worker Threads is achieved through message-passing. The parentPort object enables Workers to send messages back to the main thread, while workerData allows you to pass data to a Worker when it’s created.

For example, in the previous code, workerData contains { limit: 1000000 } that the Worker uses as an input. The Worker then sends the computed result back via parentPort.postMessage(). This way, each Worker can act independently, communicating only the essential information back to the main thread.

Error Handling in Worker Threads

Error handling is crucial in multithreaded applications to prevent crashes. Each Worker has its own error-handling mechanism, with errors being caught through the error event in the main thread. In our index.js example, this is handled by:

worker.on('error', reject);

By listening to the error event, you can manage Worker failures without impacting the main thread.

Real-World Use Cases for Worker Threads

Here are some practical use cases where Worker Threads can significantly improve performance:

Data processing and analysis: For applications that process large datasets, Worker Threads can divide the workload, reducing the processing time.
Image processing: Tasks like image resizing or format conversion can be offloaded to Worker Threads to avoid blocking the main thread.
Encryption and hashing: These CPU-bound tasks benefit greatly from parallel execution, especially in applications that handle multiple encryption requests.
Background tasks: Long-running background operations, such as periodic cleanup tasks or caching, are ideal for Workers.

Key Advantages and Limitations

Advantages:

Improved performance: Worker Threads improve the overall performance of CPU-intensive Node.js applications.
Non-blocking main thread: The main event loop remains free, which helps maintain responsiveness.
Built-in module: Worker Threads are available natively in Node.js and don’t require external dependencies.

Limitations:

Increased complexity: Multithreading introduces complexity in terms of code management and debugging.
Limited scalability: Worker Threads are limited by the CPU cores on the server, so they may not provide significant benefits in every scenario.
Not suitable for all tasks: For I/O-bound tasks, Node.js’s async model is typically more efficient than Worker Threads.

Best Practices for Using Worker Threads

Limit the number of Worker Threads: Excessive Workers can lead to resource contention and degrade performance. It’s best to match the number of Workers to your CPU cores.
Use workerData wisely: Pass only essential data to Workers to minimize memory usage.
Handle errors properly: Always use error handling to catch and respond to Worker failures.
Benchmark for your application: Test the performance impact before committing to Worker Threads, as they are most beneficial for CPU-bound tasks.

Conclusion

Worker Threads in Node.js are a powerful feature that opens up new possibilities for handling CPU-intensive operations. By offloading tasks to separate threads, you can keep the main thread responsive and improve overall application performance. However, using Worker Threads requires careful consideration of the nature of your tasks and a solid understanding of multithreading principles.

With this guide, you should have a good foundation for getting started with Worker Threads in Node.js and understanding when to use them effectively. Embrace the power of parallel processing and see the performance benefits it can bring to your Node.js applications!

Additional Resources

If you’re interested in diving deeper into Worker Threads and advanced Node.js concepts, here are some valuable resources to check out:

Node.js Official Documentation on Worker Threads

Explore the official Node.js Worker Threads documentation for comprehensive details on the module, configuration options, and more examples.
Concurrency in Node.js

Learn more about the differences between concurrency models in Node.js, including async programming and how it complements or contrasts with Worker Threads.
Performance Optimization with Node.js

Take a look at performance optimization tips for Node.js applications, which can help you decide when Worker Threads are necessary and how they fit into the larger optimization picture.
Debugging Worker Threads

Worker Threads can introduce new debugging challenges. Tools like node --inspect or using IDEs that support multithreaded debugging can help streamline the process.
Node.js Modules for Enhanced Multithreading

For advanced cases, look into third-party modules like workerpool or threads.js, which provide enhanced APIs for managing and simplifying thread pools and task queues.

Wrapping Up

By utilizing Worker Threads in Node.js, you unlock the potential for true parallelism, enabling your applications to handle CPU-bound tasks more effectively. This approach can lead to significant performance gains in scenarios that require heavy computation or extensive processing.

Worker Threads are particularly advantageous when used thoughtfully and in the right contexts, allowing you to scale Node.js applications to handle more intensive tasks without compromising the single-threaded nature of the event loop.

With this understanding, you’re ready to start experimenting with Worker Threads in your projects! Remember to measure performance improvements, handle errors gracefully, and make sure to use Worker Threads only when it benefits your application's performance.

About the Author

This article was crafted by Tamoghna Mondal, a passionate full-stack developer with experience in building scalable applications in Node.js and JavaScript. Connect on GitHub or LinkedIn to stay updated on the latest in web development.

Forem: Tamoghna

Build Your Own AI Agent with MCP: A Developer's Guide to Model Context Protocol

Build Your Own AI Agent with MCP: A Developer's Guide to Model Context Protocol

What is MCP and Why Should You Care?

The Architecture: Servers, Clients, and Protocols

🖥️ MCP Server

🤖 MCP Client

📡 Transport Protocols

Building Your First MCP Server

Sample Knowledge Base (data/kb.json)

Creating the MCP Client

Putting It All Together

Understanding Transport Protocols

stdio (What We Used)

SSE (Server-Sent Events)

Why This Approach is Powerful

Tips and Gotchas

🎯 Best Practices

⚠️ Common Pitfalls

Project Structure for Success

Going Further: Advanced Ideas

🔄 Multi-Tool Servers

🌐 Web-Based Agents

🔗 Tool Chaining

Essential Resources

Wrapping Up

Connect & Explore More

A Beginner's Guide to Worker Threads in Node.js: Unlocking Multithreading for Enhanced Performance

Introduction to Worker Threads in Node.js

What are Worker Threads in Node.js?

When to Use Worker Threads

Getting Started with Worker Threads

Basic Example of Worker Threads

Communicating Between Threads

Error Handling in Worker Threads

Real-World Use Cases for Worker Threads

Key Advantages and Limitations

Advantages:

Limitations:

Best Practices for Using Worker Threads

Conclusion

Additional Resources

Wrapping Up

About the Author

Sample Knowledge Base (`data/kb.json`)