Servers

Understanding MCP servers and how they work with Pylee

Servers

Model Context Protocol (MCP) servers are the backbone of Pylee’s extensibility. They enable Large Language Models to securely access tools, data sources, and external services through a standardized protocol.

What are MCP Servers?

MCP servers are standalone processes that expose capabilities to AI models through a well-defined protocol. Each server can provide:

• Tools: Functions the AI can execute (like file operations or API calls)
• Resources: Data sources the AI can read (like files or database records)
• Prompts: Pre-configured prompt templates for specific use cases

Server Types

Reference Servers

Official servers maintained by the MCP team, demonstrating core protocol features:

• Filesystem: Secure file operations with configurable access controls
• Fetch: Web content retrieval optimized for LLM usage
• Memory: Knowledge graph-based persistent memory system
• Sequential Thinking: Dynamic problem-solving through thought sequences

Community Servers

Third-party servers developed by the community for specific integrations and use cases.

Custom Servers

Your own servers built using MCP SDKs to integrate proprietary tools and data sources.

Server Configuration

Servers are configured in your Pylee client through JSON configuration. Each server entry specifies how to launch and connect to the server.

Basic Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Configuration with Environment Variables

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Python Server Configuration

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    },
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server_sqlite", "/path/to/database.db"]
    }
  }
}

Configuration File Location

Claude Desktop

For Claude Desktop, the configuration file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Pylee Client

Pylee looks for configuration in the following locations:

• ~/.pylee/config.json (user-specific)
• ./pylee.config.json (project-specific)
• Environment variables with PYLEE_ prefix

Configuration Options

Command Execution Parameters

• command: The executable to run (e.g., npx, python, uvx)
• args: Array of command-line arguments
• cwd: Working directory for the server process (optional)
• env: Object containing environment variables for the server

Multiple Server Configuration

You can configure multiple servers simultaneously:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/files"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Environment-Specific Configuration

Development Configuration

For development environments, you might want less restrictive settings:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/dev/workspace"
      ]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/Users/dev/workspace"]
    }
  }
}

Production Configuration

For production, use more restrictive paths and proper secret management:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/opt/app/data"
      ]
    },
    "api-server": {
      "command": "python",
      "args": ["-m", "custom_mcp_server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Server Lifecycle

Connection Process

1. Pylee launches the server process using the configured command
2. Communication is established via stdio (standard input/output)
3. Protocol negotiation occurs to establish capabilities
4. Server announces available tools, resources, and prompts

Runtime Behavior

• Servers run as separate processes for security isolation
• Communication happens through JSON-RPC messages
• Servers can maintain state between requests
• Automatic reconnection on server failures

Security Considerations

Process Isolation

Each server runs in its own process, providing security boundaries and preventing one server from affecting others.

Access Controls

Servers can implement their own access controls:

• File system servers can restrict access to specific directories
• API servers can limit which endpoints are accessible
• Database servers can enforce read-only access

Environment Variables

Sensitive configuration like API keys should be passed through environment variables, never hardcoded in configuration files.

Configuration Validation

Pylee validates your configuration on startup. Common issues include:

• Invalid JSON syntax
• Missing required server executables
• Incorrect file paths
• Missing environment variables

Server Development

Available SDKs

• TypeScript: @modelcontextprotocol/sdk
• Python: mcp
• Additional SDKs available for other languages

Basic Server Structure

A typical MCP server implements:

• Initialization: Setup and configuration
• Tool handlers: Functions that can be called by the AI
• Resource providers: Data sources the AI can access
• Prompt templates: Pre-configured prompts for specific tasks

Best Practices

• Keep servers focused on specific domains
• Implement proper error handling and logging
• Use descriptive names for tools and resources
• Provide clear documentation for server capabilities
• Follow security best practices for data access

Common Server Patterns

Data Access Servers

Provide read-only access to databases, APIs, or file systems with appropriate security controls.

Tool Servers

Expose specific functionality like code execution, file manipulation, or external service integration.

Integration Servers

Connect to third-party services like GitHub, Slack, or cloud platforms with proper authentication.

Advanced Configuration

Custom Server Arguments

Some servers accept additional configuration through command-line arguments:

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": [
        "-m", "mcp_server_postgres",
        "--host", "localhost",
        "--port", "5432",
        "--database", "myapp",
        "--read-only"
      ],
      "env": {
        "DATABASE_PASSWORD": "your_password"
      }
    }
  }
}

Server Debugging

Enable debug mode for troubleshooting:

{
  "mcpServers": {
    "debug-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "DEBUG": "mcp:*"
      }
    }
  }
}

Troubleshooting

Server Won’t Start

• Check that the command and arguments are correct
• Verify required dependencies are installed
• Review environment variables and permissions
• Check file permissions and paths

Connection Issues

• Ensure the server process is running
• Check for error messages in server logs
• Verify protocol compatibility
• Test server independently

Performance Issues

• Monitor server resource usage
• Consider implementing caching for expensive operations
• Optimize data retrieval and processing
• Check for memory leaks in long-running servers
• Optimize server startup time

Next Steps

• Explore available servers in the Pylee Registry
• Check the Troubleshooting guide for common issues
• Build your own custom server using the MCP SDKs