diff --git a/docs/mcp-usage-guide.md b/docs/mcp-usage-guide.md
new file mode 100644
index 00000000..2cb45060
--- /dev/null
+++ b/docs/mcp-usage-guide.md
@@ -0,0 +1,398 @@
+# gpt4free MCP Server - Complete Usage Guide
+
+## Table of Contents
+- [Introduction](#introduction)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Available Tools](#available-tools)
+- [Integration Examples](#integration-examples)
+- [Troubleshooting](#troubleshooting)
+
+## Introduction
+
+The gpt4free MCP (Model Context Protocol) server enables AI assistants like Claude to access powerful capabilities:
+- **Web Search**: Real-time web search using DuckDuckGo
+- **Web Scraping**: Extract and clean text content from any web page
+- **Image Generation**: Create images from text descriptions using various AI models
+
+## Quick Start
+
+### 1. Installation
+
+Make sure gpt4free is installed with all dependencies:
+
+```bash
+# Install with all features
+pip install -U g4f[all]
+
+# Or install from source
+git clone https://github.com/xtekky/gpt4free.git
+cd gpt4free
+pip install -e .
+```
+
+### 2. Start the MCP Server
+
+```bash
+# Using g4f command
+g4f mcp
+
+# Or using Python module
+python -m g4f.mcp
+
+# With debug logging
+g4f mcp --debug
+```
+
+The server will:
+- Listen on stdin for JSON-RPC requests
+- Write responses to stdout
+- Write debug/error messages to stderr
+
+### 3. Test the Server
+
+```bash
+# Send a test request
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python -m g4f.mcp
+```
+
+Expected output:
+```json
+{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "serverInfo": {...}}}
+```
+
+## Configuration
+
+### Claude Desktop
+
+1. Locate your config file:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+2. Add the MCP server:
+
+```json
+{
+  "mcpServers": {
+    "gpt4free": {
+      "command": "python",
+      "args": ["-m", "g4f.mcp"],
+      "description": "gpt4free MCP server with web search, scraping, and image generation"
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+4. Verify in Claude: Ask "What tools do you have access to?" and you should see the gpt4free tools listed.
+
+### VS Code with Cline Extension
+
+Add to your Cline MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "gpt4free": {
+      "command": "python",
+      "args": ["-m", "g4f.mcp"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any MCP-compatible client can use the server. The command is:
+```bash
+python -m g4f.mcp
+```
+
+## Available Tools
+
+### 1. web_search
+
+Search the web for current information.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `max_results` (integer, optional): Maximum results to return (default: 5)
+
+**Example Request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "web_search",
+    "arguments": {
+      "query": "latest Python 3.12 features",
+      "max_results": 5
+    }
+  }
+}
+```
+
+**Example Usage in Claude:**
+> "Search the web for the latest Python 3.12 features"
+
+### 2. web_scrape
+
+Extract text content from web pages.
+
+**Parameters:**
+- `url` (string, required): URL to scrape
+- `max_words` (integer, optional): Maximum words to extract (default: 1000)
+
+**Example Request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "web_scrape",
+    "arguments": {
+      "url": "https://python.org",
+      "max_words": 500
+    }
+  }
+}
+```
+
+**Example Usage in Claude:**
+> "Scrape the content from https://python.org and summarize it"
+
+### 3. image_generation
+
+Generate images from text descriptions.
+
+**Parameters:**
+- `prompt` (string, required): Image description
+- `model` (string, optional): Image model (default: "flux")
+- `width` (integer, optional): Width in pixels (default: 1024)
+- `height` (integer, optional): Height in pixels (default: 1024)
+
+**Example Request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "image_generation",
+    "arguments": {
+      "prompt": "A serene mountain landscape at sunset",
+      "width": 1024,
+      "height": 1024
+    }
+  }
+}
+```
+
+**Example Usage in Claude:**
+> "Generate an image of a serene mountain landscape at sunset"
+
+## Integration Examples
+
+### Python Script
+
+```python
+import asyncio
+import json
+from g4f.mcp.server import MCPServer, MCPRequest
+
+async def search_web(query: str):
+    server = MCPServer()
+    request = MCPRequest(
+        jsonrpc="2.0",
+        id=1,
+        method="tools/call",
+        params={
+            "name": "web_search",
+            "arguments": {"query": query}
+        }
+    )
+    response = await server.handle_request(request)
+    return response.result
+
+# Run it
+result = asyncio.run(search_web("Python tutorials"))
+print(result)
+```
+
+### Command Line Testing
+
+```bash
+# Test initialize
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | g4f mcp
+
+# Test list tools
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | g4f mcp
+
+# Test web search
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"test"}}}' | g4f mcp
+```
+
+### Using with Shell Scripts
+
+```bash
+#!/bin/bash
+# search.sh - Simple web search wrapper
+
+query="$1"
+request=$(cat <<EOF
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"$query"}}}
+EOF
+)
+
+echo "$request" | python -m g4f.mcp | jq '.result.content[0].text | fromjson'
+```
+
+## Troubleshooting
+
+### Server Won't Start
+
+**Problem**: Server exits immediately or shows import errors
+
+**Solution**:
+```bash
+# Install all dependencies
+pip install -r requirements.txt
+
+# Or install with all extras
+pip install -U g4f[all]
+```
+
+### Tools Return Errors
+
+**Problem**: Tools return error messages about missing packages
+
+**Solution**: Install specific dependencies:
+```bash
+# For web search
+pip install ddgs beautifulsoup4
+
+# For web scraping
+pip install aiohttp beautifulsoup4
+
+# For image generation
+pip install pillow
+```
+
+### Network Errors
+
+**Problem**: Tools fail with connection errors
+
+**Solution**:
+- Check internet connectivity
+- Some providers may be rate-limited
+- Try different providers for image generation
+- Check firewall settings
+
+### Claude Desktop Not Finding Server
+
+**Problem**: Claude doesn't show gpt4free tools
+
+**Solution**:
+1. Verify config file location and syntax
+2. Check that Python is in PATH
+3. Try absolute path to Python:
+   ```json
+   {
+     "mcpServers": {
+       "gpt4free": {
+         "command": "/usr/bin/python3",
+         "args": ["-m", "g4f.mcp"]
+       }
+     }
+   }
+   ```
+4. Restart Claude Desktop completely
+5. Check Claude logs for errors
+
+### Debug Mode
+
+Enable debug output:
+```bash
+# Redirect stderr to see debug messages
+g4f mcp 2> mcp_debug.log
+
+# Run with verbose output
+g4f mcp --debug 2>&1 | tee mcp_output.log
+```
+
+### Verify Installation
+
+Run the test script:
+```bash
+python etc/testing/test_mcp_server.py
+```
+
+Or the interactive demo:
+```bash
+python etc/testing/test_mcp_interactive.py
+```
+
+## Protocol Details
+
+The MCP server implements JSON-RPC 2.0 over stdio transport.
+
+**Supported Methods:**
+- `initialize` - Initialize the connection
+- `tools/list` - List all available tools  
+- `tools/call` - Execute a tool
+- `ping` - Health check
+
+**Message Format:**
+- Requests: One JSON object per line on stdin
+- Responses: One JSON object per line on stdout
+- Logs: Messages on stderr
+
+## Advanced Usage
+
+### Custom Tool Development
+
+To add custom tools, see `g4f/mcp/tools.py`:
+
+```python
+from g4f.mcp.tools import MCPTool
+
+class MyCustomTool(MCPTool):
+    @property
+    def description(self) -> str:
+        return "My custom tool description"
+    
+    @property
+    def input_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "param1": {"type": "string", "description": "..."}
+            },
+            "required": ["param1"]
+        }
+    
+    async def execute(self, arguments: Dict[str, Any]) -> Any:
+        # Your implementation
+        pass
+```
+
+Register in `g4f/mcp/server.py`:
+```python
+self.tools['my_tool'] = MyCustomTool()
+```
+
+## Support
+
+- Documentation: [g4f/mcp/README.md](README.md)
+- Issues: https://github.com/xtekky/gpt4free/issues
+- MCP Specification: https://modelcontextprotocol.io/
+
+## License
+
+Part of the gpt4free project, licensed under GNU General Public License v3.0.
diff --git a/etc/examples/mcp_tools_demo.py b/etc/examples/mcp_tools_demo.py
new file mode 100644
index 00000000..87261a71
--- /dev/null
+++ b/etc/examples/mcp_tools_demo.py
@@ -0,0 +1,201 @@
+#!/usr/bin/env python
+"""
+Example: Using the MCP Server Tools
+
+This script demonstrates how to interact with the MCP server tools programmatically.
+It shows how each tool can be used and what kind of results to expect.
+"""
+
+import asyncio
+import json
+from g4f.mcp.server import MCPServer, MCPRequest
+
+
+async def demo_web_search():
+    """Demonstrate web search tool"""
+    print("\n" + "=" * 70)
+    print("DEMO: Web Search Tool")
+    print("=" * 70)
+    
+    server = MCPServer()
+    
+    # Create a tool call request for web search
+    request = MCPRequest(
+        jsonrpc="2.0",
+        id=1,
+        method="tools/call",
+        params={
+            "name": "web_search",
+            "arguments": {
+                "query": "Python programming tutorials",
+                "max_results": 3
+            }
+        }
+    )
+    
+    print("\nRequest:")
+    print(json.dumps({
+        "method": "tools/call",
+        "params": request.params
+    }, indent=2))
+    
+    print("\nExecuting web search...")
+    response = await server.handle_request(request)
+    
+    if response.result:
+        print("\nSuccess! Response:")
+        content = response.result.get("content", [])
+        if content:
+            result_text = content[0].get("text", "")
+            result_data = json.loads(result_text)
+            print(json.dumps(result_data, indent=2))
+    elif response.error:
+        print(f"\nError: {response.error}")
+
+
+async def demo_web_scrape():
+    """Demonstrate web scraping tool"""
+    print("\n" + "=" * 70)
+    print("DEMO: Web Scrape Tool")
+    print("=" * 70)
+    
+    server = MCPServer()
+    
+    # Create a tool call request for web scraping
+    request = MCPRequest(
+        jsonrpc="2.0",
+        id=2,
+        method="tools/call",
+        params={
+            "name": "web_scrape",
+            "arguments": {
+                "url": "https://example.com",
+                "max_words": 200
+            }
+        }
+    )
+    
+    print("\nRequest:")
+    print(json.dumps({
+        "method": "tools/call",
+        "params": request.params
+    }, indent=2))
+    
+    print("\nExecuting web scrape...")
+    response = await server.handle_request(request)
+    
+    if response.result:
+        print("\nSuccess! Response:")
+        content = response.result.get("content", [])
+        if content:
+            result_text = content[0].get("text", "")
+            result_data = json.loads(result_text)
+            print(json.dumps(result_data, indent=2))
+    elif response.error:
+        print(f"\nError: {response.error}")
+
+
+async def demo_image_generation():
+    """Demonstrate image generation tool"""
+    print("\n" + "=" * 70)
+    print("DEMO: Image Generation Tool")
+    print("=" * 70)
+    
+    server = MCPServer()
+    
+    # Create a tool call request for image generation
+    request = MCPRequest(
+        jsonrpc="2.0",
+        id=3,
+        method="tools/call",
+        params={
+            "name": "image_generation",
+            "arguments": {
+                "prompt": "A beautiful sunset over mountains",
+                "model": "flux",
+                "width": 512,
+                "height": 512
+            }
+        }
+    )
+    
+    print("\nRequest:")
+    print(json.dumps({
+        "method": "tools/call",
+        "params": request.params
+    }, indent=2))
+    
+    print("\nExecuting image generation...")
+    response = await server.handle_request(request)
+    
+    if response.result:
+        print("\nSuccess! Response:")
+        content = response.result.get("content", [])
+        if content:
+            result_text = content[0].get("text", "")
+            result_data = json.loads(result_text)
+            # Don't print the full base64 image data, just show metadata
+            if "image" in result_data and result_data["image"].startswith("data:"):
+                result_data["image"] = result_data["image"][:100] + "... (base64 data truncated)"
+            print(json.dumps(result_data, indent=2))
+    elif response.error:
+        print(f"\nError: {response.error}")
+
+
+async def main():
+    """Run all demos"""
+    print("\n" + "=" * 70)
+    print("gpt4free MCP Server - Tool Demonstrations")
+    print("=" * 70)
+    print("\nThis script demonstrates the three main tools available in the MCP server:")
+    print("1. Web Search - Search the web using DuckDuckGo")
+    print("2. Web Scrape - Extract content from web pages")
+    print("3. Image Generation - Generate images from text prompts")
+    print("\nNote: These tools require network access and may fail in isolated environments.")
+    
+    # Show tool information
+    print("\n" + "=" * 70)
+    print("Available Tools")
+    print("=" * 70)
+    
+    server = MCPServer()
+    for name, tool in server.tools.items():
+        print(f"\n• {name}")
+        print(f"  Description: {tool.description}")
+        schema = tool.input_schema
+        required = schema.get("required", [])
+        properties = schema.get("properties", {})
+        print(f"  Required parameters: {', '.join(required)}")
+        print(f"  Optional parameters: {', '.join([k for k in properties.keys() if k not in required])}")
+    
+    # Run demos (these may fail without network access or required packages)
+    try:
+        await demo_web_search()
+    except Exception as e:
+        print(f"\n⚠ Web search demo failed: {e}")
+        print("This is expected without network access or required packages (ddgs, beautifulsoup4)")
+    
+    try:
+        await demo_web_scrape()
+    except Exception as e:
+        print(f"\n⚠ Web scrape demo failed: {e}")
+        print("This is expected without network access or required packages (aiohttp, beautifulsoup4)")
+    
+    try:
+        await demo_image_generation()
+    except Exception as e:
+        print(f"\n⚠ Image generation demo failed: {e}")
+        print("This is expected without network access or image generation providers")
+    
+    print("\n" + "=" * 70)
+    print("Demo Complete")
+    print("=" * 70)
+    print("\nTo use these tools in production:")
+    print("1. Start the MCP server: g4f mcp")
+    print("2. Configure your AI assistant to connect to it")
+    print("3. The assistant can then use these tools to enhance its capabilities")
+    print("\nSee g4f/mcp/README.md for detailed configuration instructions.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())