Using MCP Server Templates¶

Comprehensive guide for integrating deployed MCP server templates with various clients and development environments.

🎯 Overview¶

Once you've deployed an MCP server template, you can integrate it with: - Claude Desktop: For AI-powered workflows - VS Code: For development environments - Python Applications: For programmatic access - Other MCP-compatible clients: Custom integrations

📋 Prerequisites¶

Before integrating, ensure you have: 1. Deployed server: mcp-template deploy <template-name> 2. Container name: Note the container name from deployment output 3. Configuration: Know your server's configuration options

🔧 Integration Methods¶

Method 1: Claude Desktop Integration¶

Perfect for AI-powered document processing, analysis, and automation.

1. Find Your Container Name¶

# List running MCP containers
docker ps --filter "label=mcp.template-id" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# Example output:
# mcp-file-server-0725-123456-abcdef    dataeverything/mcp-file-server:latest    Up 2 minutes
# mcp-demo-0725-789012-ghijkl           dataeverything/mcp-demo:latest           Up 1 minute

2. Update Claude Desktop Configuration¶

Location: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "your-server-name": {
      "command": "docker",
      "args": ["exec", "-i", "CONTAINER_NAME", "python", "-m", "src.server"]
    }
  }
}

Example for multiple templates:

{
  "mcpServers": {
    "file-server": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-file-server-0725-123456-abcdef", "python", "-m", "src.server"]
    },
    "demo-server": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-demo-0725-789012-ghijkl", "python", "-m", "src.server"]
    }
  }
}

3. Restart Claude Desktop¶

After updating the configuration: 1. Quit Claude Desktop completely 2. Restart the application 3. Verify connection: Look for your server in the MCP section

4. Usage in Claude Desktop¶

Example prompts:
• "List files in my Documents folder" (file-server)
• "Say hello to Alice" (demo server)
• "Get server information" (any server)
• "Show me the configuration options"

Method 2: VS Code Integration¶

Ideal for development workflows and code analysis.

1. Install MCP Extension¶

# Install the MCP extension for VS Code
code --install-extension mcp-client

2. Configure VS Code Settings¶

File: .vscode/settings.json in your workspace

{
  "mcp.servers": {
    "file-server": {
      "command": "docker",
      "args": ["exec", "-i", "CONTAINER_NAME", "python", "-m", "src.server"],
      "description": "File system access server"
    },
    "demo-server": {
      "command": "docker",
      "args": ["exec", "-i", "CONTAINER_NAME", "python", "-m", "src.server"],
      "description": "Demo greeting server"
    }
  }
}

3. Use MCP Tools in VS Code¶

Command Palette: Ctrl+Shift+P → "MCP: List Tools"
Tool Execution: Select and run tools directly
Integration: Use with GitHub Copilot Chat

Method 3: Python Integration¶

For programmatic access and custom applications.

1. Install MCP Client¶

pip install mcp

2. Basic Python Client¶

import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

class MCPClient:
    def __init__(self, container_name: str):
        self.server_params = StdioServerParameters(
            command="docker",
            args=["exec", "-i", container_name, "python", "-m", "src.server"]
        )

    async def connect(self):
        """Establish connection to MCP server."""
        self.client = stdio_client(self.server_params)
        self.read, self.write = await self.client.__aenter__()
        self.session = ClientSession(self.read, self.write)
        await self.session.initialize()
        return self.session

    async def list_tools(self):
        """List available tools."""
        tools = await self.session.list_tools()
        return [(tool.name, tool.description) for tool in tools.tools]

    async def call_tool(self, name: str, args: dict = None):
        """Call a specific tool."""
        result = await self.session.call_tool(name, args or {})
        return result.content[0].text

    async def disconnect(self):
        """Close the connection."""
        await self.client.__aexit__(None, None, None)

# Usage example
async def main():
    client = MCPClient("mcp-demo-0725-789012-ghijkl")

    try:
        await client.connect()

        # List available tools
        tools = await client.list_tools()
        print("Available tools:", tools)

        # Call a tool
        greeting = await client.call_tool("say_hello", {"name": "World"})
        print("Greeting:", greeting)

    finally:
        await client.disconnect()

# Run the client
asyncio.run(main())

3. Advanced Python Usage¶

import asyncio
from typing import Dict, Any, List

class AdvancedMCPClient(MCPClient):
    async def batch_operations(self, operations: List[Dict[str, Any]]):
        """Execute multiple operations in sequence."""
        results = []
        for op in operations:
            result = await self.call_tool(op['tool'], op.get('args', {}))
            results.append({
                'operation': op,
                'result': result
            })
        return results

    async def health_check(self):
        """Check server health and capabilities."""
        try:
            tools = await self.list_tools()
            return {
                'status': 'healthy',
                'tools_count': len(tools),
                'tools': tools
            }
        except Exception as e:
            return {
                'status': 'unhealthy',
                'error': str(e)
            }

# Batch operations example
async def process_batch():
    client = AdvancedMCPClient("mcp-file-server-0725-123456-abcdef")

    await client.connect()

    operations = [
        {'tool': 'list_directory', 'args': {'path': '/home/user/docs'}},
        {'tool': 'read_file', 'args': {'path': '/home/user/docs/readme.txt'}},
        {'tool': 'get_file_info', 'args': {'path': '/home/user/docs/readme.txt'}}
    ]

    results = await client.batch_operations(operations)

    for result in results:
        print(f"Tool {result['operation']['tool']}: {result['result']}")

    await client.disconnect()

Method 4: Manual CLI Testing¶

For testing and debugging server functionality.

1. Interactive Testing¶

# Connect directly to the server
docker exec -it CONTAINER_NAME python -m src.server

# Or use our test client
python test_demo_client.py

2. Tool Testing¶

# Test specific functionality
docker exec CONTAINER_NAME python -c "
import asyncio
from src.server import DemoServer

async def test():
    server = DemoServer()
    # Test tool directly (bypassing MCP protocol)
    result = await server._register_tools.__wrapped__(server).say_hello('Test')
    print(result)

asyncio.run(test())
"

🛠️ Configuration Management¶

Environment Variables¶

All templates support environment variable configuration:

# Deploy with custom configuration
mcp-template deploy template-name \
  --config key1=value1 \
  --config key2=value2 \
  --env CUSTOM_VAR=custom_value

Configuration Files¶

# Using configuration file
mcp-template deploy template-name \
  --config-file my-config.json

Example config file (my-config.json):

{
  "hello_from": "My Custom App",
  "log_level": "debug",
  "timeout": 60,
  "features": ["feature1", "feature2"]
}

Dynamic Configuration¶

# Show available configuration options
mcp-template deploy template-name --show-config

# Deploy with double underscore notation for nested config
mcp-template deploy template-name \
  --config security__read_only=true \
  --config logging__level=debug

🐛 Troubleshooting¶

Common Issues¶

1. Container Not Found¶

# Check running containers
docker ps --filter "label=mcp.template-id"

# If no containers, redeploy
mcp-template deploy template-name

2. Connection Refused¶

# Check container logs
docker logs CONTAINER_NAME

# Check container is running
docker exec CONTAINER_NAME ps aux

3. Tool Not Working¶

# Test tool directly
docker exec -it CONTAINER_NAME python -c "
import sys
sys.path.append('/app')
from src.server import *
# Test server initialization
"

Debug Mode¶

# Deploy with debug logging
mcp-template deploy template-name \
  --config log_level=debug

# View debug logs
docker logs -f CONTAINER_NAME

📊 Monitoring and Management¶

Container Management¶

# List all MCP containers
docker ps --filter "label=mcp.template-id" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

# Stop specific template
mcp-template stop template-name

# View logs
mcp-template logs template-name

# Access shell
mcp-template shell template-name

Health Monitoring¶

# Health check script
import asyncio
import docker

async def check_mcp_servers():
    client = docker.from_env()
    containers = client.containers.list(filters={
        "label": "mcp.template-id"
    })

    for container in containers:
        print(f"Container: {container.name}")
        print(f"Status: {container.status}")
        print(f"Health: {container.attrs.get('State', {}).get('Health', {}).get('Status', 'N/A')}")
        print("-" * 40)

asyncio.run(check_mcp_servers())

🔗 Next Steps¶

After successful integration:

Template-Specific Usage: Check docs/server-templates/<template-name>/ for specific examples
Advanced Configuration: See docs/guides/configuration.md
Development: See docs/development/template-development.md
Contributing: See docs/guides/contributing.md

📚 Resources¶

Template Documentation: docs/server-templates/
Configuration Guide: docs/guides/configuration.md
MCP Protocol: Model Context Protocol Specification
Support: tooling@dataeverything.ai