mcp-buildatool by amiller - MCP Server

Dynamic Toolbox MCP Server

A Model Context Protocol (MCP) server that allows AI agents to dynamically create, manage, and execute their own Python script tools at runtime.

Overview

This project provides a complete MCP server setup with OAuth authentication and SSL support, enabling AI to expand its capabilities by writing and deploying custom Python tools on demand.

Architecture

┌─────────────────┐    HTTPS/OAuth    ┌─────────────────┐    HTTP    ┌─────────────────┐
│   Claude AI     │ ──────────────────▶│   SSL Proxy     │ ──────────▶│   MCP Server    │
│                 │                    │   (Port 9100)   │            │   (Port 9101)   │
└─────────────────┘                    └─────────────────┘            └─────────────────┘
                                              │
                                              ▼
                                       ┌─────────────────┐
                                       │ OAuth Server    │
                                       │ & Certificate   │
                                       │ Management      │
                                       └─────────────────┘

Features

🔧 Dynamic Tool Management

Create: Add new Python script tools with custom parameters
Read: View tool details and code
Update: Modify existing tools (code, description, parameters)
Delete: Remove tools from the toolbox
Execute: Run tools with parameters in isolated environment

🔒 Security & Authentication

OAuth 2.1: Full authorization server with client registration
Multiple Grant Types: Authorization Code + PKCE and Client Credentials flows
SSL/TLS: HTTPS encryption using Let's Encrypt certificates
Sandboxing: Tools execute in isolated subprocess with 30s timeout
Validation: Python code syntax checking before tool creation

🌐 Network Capabilities

Remote APIs: Tools can make HTTP/HTTPS requests
Web Scraping: Support for BeautifulSoup and similar libraries
File Operations: Read/write files in the working directory
Full Python: Access to all installed packages and standard library

📊 Client Monitoring & Analytics

OAuth Client Tracking: Monitor registered clients and authentication flows
Session Management: Track unique MCP sessions per chat/conversation
Activity Logging: Detailed logs of tool usage and client behavior
User Agent Analysis: Identify client software and versions

Quick Start

Prerequisites

Python 3.11+
SSL certificates (location configurable via environment variables)
Packages: fastmcp, authlib, requests, flask, python-dotenv

Installation

pip install -r requirements.txt

Configuration

Copy the environment template:

cp .env.example .env

Edit .env with your domain and configuration:

DOMAIN=your-domain.com
MCP_HOST=127.0.0.1
MCP_PORT=9101
PROXY_HOST=0.0.0.0
PROXY_PORT=9100
USE_SSL=true

Running the Services

Start the MCP Server (localhost:9101):

python dynamic_toolbox_mcp.py

Start the OAuth+SSL Proxy (0.0.0.0:9100):

python ssl_proxy.py

Connecting from Claude

Add this MCP server configuration:

{
  "name": "Dynamic Toolbox",
  "url": "https://your-domain.com",
  "auth": {
    "type": "oauth2",
    "authorization_endpoint": "https://your-domain.com/oauth/authorize",
    "token_endpoint": "https://your-domain.com/token",
    "registration_endpoint": "https://your-domain.com/register"
  }
}

Available Tools

Core CRUD Operations

`create_tool(name, description, code, parameters)`

Create a new Python script tool.

Example:

create_tool(
    name="add_numbers",
    description="Add two numbers together",
    code='''
def main(x, y):
    return x + y
''',
    parameters={
        "type": "object",
        "properties": {
            "x": {"type": "number", "description": "First number"},
            "y": {"type": "number", "description": "Second number"}
        },
        "required": ["x", "y"]
    }
)

`execute_tool(name, parameters)`

Run a tool with the specified parameters.

Example:

execute_tool("add_numbers", {"x": 5, "y": 3})
# Returns: "8"

`list_tools()`

Get all available tools with their metadata.

`get_tool(name)`

Retrieve full details of a specific tool including source code.

`update_tool(name, description?, code?, parameters?)`

Modify an existing tool.

`delete_tool(name)`

Remove a tool from the toolbox.

Code Structure

Tool Requirements

Tools must define either:

A main(**params) function that accepts the tool parameters
A single function (auto-detected if no main() exists)

Execution Environment

Timeout: 30 seconds maximum
Working Directory: /home/amiller/projects/buildatool
Python Version: 3.11
Network: Full internet access
Libraries: All installed packages available
File System: Read/write access to current directory

Error Handling

Tools should handle exceptions gracefully:

def main(url):
    try:
        response = requests.get(url)
        return response.json()
    except Exception as e:
        return {"error": str(e)}

Examples

See for detailed examples including:

REST API client
Web scraper
RSS feed reader
And more!

File Structure

buildatool/
├── dynamic_toolbox_mcp.py    # Main MCP server
├── ssl_proxy.py              # OAuth+SSL proxy
├── test_toolbox.py           # Test suite
├── requirements.txt          # Dependencies
├── toolbox_data/             # Tool storage
│   └── tools.json           # Tool definitions
├── certs/                    # SSL certificates
└── README.md                # This file

Development

Testing

python test_toolbox.py

Environment Variables

DOMAIN: Your SSL certificate domain (default: your-domain.com)
MCP_HOST: MCP server host (default: 127.0.0.1)
MCP_PORT: MCP server port (default: 9101)
PROXY_HOST: Proxy host (default: 0.0.0.0)
PROXY_PORT: Proxy port (default: 9100)
USE_SSL: Enable SSL/HTTPS (default: true)
SSL_CERT_PATH: Path to SSL certificate (default: ./certs/live/{DOMAIN}/fullchain.pem)
SSL_KEY_PATH: Path to SSL private key (default: ./certs/live/{DOMAIN}/privkey.pem)

Logs

Both services provide detailed logging:

MCP server: FastMCP logs with tool execution details
Proxy: Flask logs with OAuth and proxy activity

Security Considerations

Tools run in subprocess but aren't fully sandboxed
Full file system access within working directory
Network access is unrestricted
SSL certificates should be properly managed
OAuth tokens have 1-hour expiration by default

Limitations

No persistent state between tool executions
30-second execution timeout
No interactive input support
Single-threaded tool execution
In-memory storage (tools reset on server restart)

Contributing

The codebase follows the ambient_mcp pattern for OAuth and SSL handling. Key principles:

Minimal dependencies
Clear error handling
Comprehensive logging
Security-first design

License

This project builds upon FastMCP and follows similar patterns to ambient_mcp for OAuth implementation.