MCP Demo Server

You can run and interact with an MCP server that exposes tools, resources, and prompts to guide LLMs in context-aware tasks. This server also includes an intelligent Agent System with subagents and an orchestrator to manage complex workflows, retries, and parallel execution, enabling robust, end-to-end automation.

How to use

You connect an MCP client to the server to discover available tools, read resources, and fetch prompts. Use the client to submit tasks that leverage the Calculator, File Operations, Weather, and Timestamp tools. The Agent System can delegate work to specialized SubAgents, orchestrate workflows, and aggregate results. Start workflows that involve multiple steps, parallel execution, and data processing pipelines, and rely on the built-in task management for status tracking and retries.

How to install

# Prerequisites
- Python 3.10 or higher
- pip (Python package manager)

# Install from source in editable mode
git clone https://github.com/yourusername/mcp-agent.git
cd mcp-agent
pip install -e .

# Install production dependencies (alternative)
pip install -r requirements.txt

Configuration and running the MCP server

You have two ways to run the server locally. Choose the method you prefer and use the corresponding command in a terminal.

# Run the MCP server directly via Python
python -m mcp_demo.server

# Or use the installed executable script
mcp-demo

Additional usage notes

The server exposes four tool families and three categories of resources and prompts. You can test interactions with the included example client, or integrate the server into your own MCP client setup. If you plan to connect Claude Desktop or other MCP clients, configure the appropriate MCP server entry in your client’s configuration to point at the local stdio startup commands shown above.

Troubleshooting and tips

If you encounter issues during setup or execution, verify you are using the correct Python version and that dependencies are installed. For startup problems, ensure the command for the stdio entry is exactly as shown and that the working directory has the necessary permissions. If the server process does not appear in your MCP client, double-check the command and arguments in your client configuration and restart the client.

Examples and quick-starts

# Example: Run the comprehensive agent system demo
python examples/agent_demo.py

# Example: Quick agent system usage with subagents
python -c "import asyncio; from mcp_demo import Agent, CalculatorSubAgent, FileOperationsSubAgent, Task; \
async def main():\n    main_agent = Agent(name='MainAgent')\n    calc_sub = CalculatorSubAgent(parent_agent=main_agent)\n    file_sub = FileOperationsSubAgent(parent_agent=main_agent)\n    calc_task = Task(name='Calculate', task_type='calculation', parameters={'operation':'add','a':10,'b':20})\n    async with main_agent, calc_sub, file_sub:\n        result = await main_agent.execute_task(calc_task)\n        print(result.data)\nasyncio.run(main())""

Server configuration and prompts overview

The server exposes configuration endpoints for tools, resources, and prompts that you can query from your MCP client. Use the available tools to perform calculations, file operations, fetch weather data, and obtain timestamps. Read resources like server settings and system information, and request prompts such as code reviews or documentation templates to drive LLM interactions.

Running with Claude Desktop or MCP clients

If you use Claude Desktop, add the MCP server entry to your Claude configuration so the client can launch the server as needed. The standard approach is to run the server locally and point Claude to the corresponding startup command.

Project structure and where to look next

You will find the server implementation, agent system, subagents, orchestrator, and task management in the project’s source tree. Explore the server entry point, agent logic, and subagent behaviors to customize or extend capabilities.

Notes on language and tooling

The server is implemented in Python and uses standard tooling such as pip for dependencies. The primary language for extending or scripting the server is Python.

Security and reliability notes

The design emphasizes input validation, error handling, and safe resource interactions. When adding new tools or resources, validate inputs, handle edge cases, and implement timeouts to prevent runaway tasks.

Available tools

calculator

Performs basic mathematical operations with input validation and error handling.

file_operations

Reads, writes, lists directories, checks file existence with safe path handling.

weather

Provides simulated weather information for a city with Celsius and Fahrenheit support.

timestamp

Returns current time in multiple formats such as ISO, Unix timestamp, and human-readable form.