Content
# Code Execution with MCP - Template Repository
A production-ready template for building AI agents using the **Code Execution with MCP** pattern. This harness enables AI agents to dynamically discover and execute MCP tools through secure, sandboxed code execution.
> **Inspired by**: This template implements the architectural patterns and design philosophy from Anthropic's [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) engineering blog post and their [Skills Repository](https://github.com/anthropics/skills). We are grateful to Anthropic for openly sharing these patterns.
## 🌟 Key Features
- **Dynamic Tool Discovery** - Tools discovered at runtime using `list_mcp_tools()` and `get_mcp_tool_details()` (no static files)
- **Secure Sandbox Execution** - Docker-based isolation with resource limits, read-only filesystem, and network restrictions
- **PII Protection** - Automatic tokenization/de-tokenization of sensitive data
- **Persistent Skills** - `/skills` directory for reusable agent code
- **Ephemeral Workspace** - `/workspace` directory for temporary task files
- **Multi-Turn Conversations** - Support for complex agent workflows
- **Extensible Architecture** - Easy to customize and extend
## 💡 Why Code Execution?
**The Token Efficiency Problem**: Traditional AI agents must describe every computational step in natural language, consuming valuable context window space. Processing 1,000 records might use 50,000 tokens just to describe the transformations.
**The Solution**: Code execution lets agents write and run code, delegating computation to traditional software while focusing their intelligence on high-level reasoning. The same 1,000-record task uses just ~500 tokens of code.
**Key Benefits**:
- 📊 **Scalability**: Handle tasks of any complexity within token limits
- 🔄 **Reusability**: Save code to `/skills` for future use
- 🔒 **Privacy**: PII tokenized before reaching the LLM
- 🎯 **Reliability**: Deterministic code execution vs. natural language descriptions
> 📖 Read the full philosophy in [`docs/PHILOSOPHY.md`](docs/PHILOSOPHY.md) - explains the "why" behind this architecture based on Anthropic's research.
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ User / Application │
└────────────────────┬────────────────────────────────────────┘
│ HTTP Request
▼
┌─────────────────────────────────────────────────────────────┐
│ Agent Orchestrator │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ AgentManager │◄─┤ PII Censor │◄─┤ MCP Client │ │
│ └──────┬───────┘ └──────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ LLM Provider │ (OpenAI, Anthropic, etc.) │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Sandbox Manager (Docker) │ │
│ └──────┬───────────────────────────┘ │
└─────────┼────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Secure Docker Container │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Agent Code Execution │ │
│ │ - Runtime API (callMCPTool, fs, utils) │ │
│ │ - Dynamic Tool Discovery │ │
│ │ - /skills (persistent, mounted) │ │
│ │ - /workspace (ephemeral, mounted) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ Security: Non-root user, read-only rootfs, resource limits │
└─────────────────────────────────────────────────────────────┘
│
│ Authenticated API Call
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Servers │
│ (File System, Databases, APIs, Custom Tools) │
└─────────────────────────────────────────────────────────────┘
```
## 🚀 Quick Start
### Prerequisites
- Node.js >= 18.0.0
- Docker (for sandbox execution)
- TypeScript knowledge
### Installation
```bash
# Clone the repository
git clone <your-repo-url>
cd code-execution-with-MCP
# Install dependencies
npm install
# Build the project
npm run build
# Build the Docker sandbox image
npm run build-sandbox
# Create required directories
npm run prepare-workspace
# Start the server
npm start
```
### Development
```bash
# Run in development mode with auto-reload
npm run dev
# Type checking only
npm run type-check
# Clean build artifacts
npm run clean
```
## 📁 Project Structure
```
mcp-code-exec-harness/
├── src/
│ ├── agent_orchestrator/ # Main agent logic
│ │ ├── AgentManager.ts # Agent execution loop
│ │ └── prompt_templates.ts # System prompts
│ │
│ ├── sandbox_manager/ # Secure code execution
│ │ ├── SandboxManager.ts # Abstract interface
│ │ └── DockerSandbox.ts # Docker implementation
│ │
│ ├── mcp_client/ # MCP communication
│ │ ├── McpClient.ts # MCP server client
│ │ └── PiiCensor.ts # PII tokenization
│ │
│ ├── agent_runtime/ # Sandbox runtime API
│ │ └── runtime_api.ts # Injected helper functions
│ │
│ ├── tools_interface/ # Dynamic tool discovery
│ │ └── DynamicToolManager.ts
│ │
│ └── index.ts # Main server entry point
│
├── servers/ # MCP server collection (NEW!)
│ ├── official/ # Official MCP servers
│ ├── archived/ # Archived reference servers
│ ├── community/ # Community-contributed servers
│ ├── README.md # Server collection documentation
│ ├── catalog.json # Structured server index
│ └── QUICKSTART.md # Quick start guide
│
├── skills/ # Persistent agent skills (user-specific)
├── workspace/ # Ephemeral execution workspace
├── Dockerfile.sandbox # Secure sandbox container
├── package.json
├── tsconfig.json
└── README.md
```
## 🔧 Configuration
### Environment Variables
Create a `.env` file in the root directory:
```env
# Server Configuration
PORT=3000
NODE_ENV=development
# Sandbox Configuration
SANDBOX_IMAGE=sandbox-image-name
SANDBOX_TIMEOUT_MS=30000
SANDBOX_MEMORY_MB=100
SANDBOX_CPU_QUOTA=50000
# LLM Provider (configure for your provider)
LLM_API_KEY=your-api-key-here
LLM_MODEL=your-model-name
# MCP Servers (customize for your setup)
# Add your MCP server configurations here
```
### Customizing the Agent
1. **Implement LLM Integration** - Edit `src/agent_orchestrator/AgentManager.ts`:
```typescript
async function callLLM(prompt: string, tools: any[]): Promise<LLMResponse> {
// Add your LLM API call here
// Examples: OpenAI, Anthropic, Google Gemini, etc.
}
```
2. **Connect MCP Servers** - Edit `src/mcp_client/McpClient.ts`:
```typescript
private initializeServers(): void {
// Add your MCP server connections
// Use @modelcontextprotocol/sdk
}
```
3. **Customize System Prompts** - Edit `src/agent_orchestrator/prompt_templates.ts`
4. **Adjust Sandbox Security** - Edit `src/sandbox_manager/DockerSandbox.ts`
## 🔐 Security Features
### Sandbox Isolation
- **Non-root execution** - Runs as `sandboxuser`
- **Read-only root filesystem** - Prevents system modifications
- **Resource limits** - CPU and memory constraints
- **Network restrictions** - Configurable network access
- **Capability dropping** - Minimal container privileges
### PII Protection
Automatic detection and tokenization of:
- Email addresses
- Phone numbers
- Social Security Numbers
- Credit card numbers
- IP addresses
- Custom patterns (extensible)
### Authentication
- Session-specific auth tokens for sandbox ↔ host communication
- Validate tokens in production deployment
## 📚 Usage Examples
### Making a Request
```bash
curl -X POST http://localhost:3000/task \
-H "Content-Type: application/json" \
-d '{
"userId": "user123",
"task": "Analyze the latest sales data and create a summary report"
}'
```
### Agent Code Example
The agent writes code like this (executed in sandbox):
```javascript
// 1. Discover available tools
const tools = await list_mcp_tools();
console.log("Available tools:", tools);
// 2. Get tool details
const dbTool = await get_mcp_tool_details("database__query");
console.log("Tool info:", dbTool.description);
// 3. Execute tools
const salesData = await callMCPTool("database__query", {
query: "SELECT * FROM sales WHERE date > '2024-01-01'"
});
// 4. Process data in code
const summary = salesData.reduce((acc, sale) => {
acc.total += sale.amount;
acc.count += 1;
return acc;
}, { total: 0, count: 0 });
// 5. Save to skills for reuse
await fs.writeFile('/skills/sales_summary.js', `
module.exports = async function summarizeSales(data) {
return data.reduce((acc, sale) => {
acc.total += sale.amount;
acc.count += 1;
return acc;
}, { total: 0, count: 0 });
};
`);
// 6. Return results
return { summary, totalSales: summary.total, count: summary.count };
```
## 🛠️ Extending the Template
### MCP Servers Collection
This repository includes a comprehensive collection of **18 MCP servers** organized for progressive discovery:
- **📦 7 Official Servers** - Filesystem, Git, Memory, Fetch, Everything, Time, Sequential Thinking
- **🗄️ 5 Archived Servers** - PostgreSQL, Redis, SQLite, Puppeteer, Sentry
- **🌍 6 Community Servers** - MongoDB, GreptimeDB, Unstructured, Semgrep, MCP Installer, PostgreSQL Community Fork
**Quick Start:**
```bash
# Browse the server collection
cd servers/
# Read the documentation
cat README.md
# Check the quick start guide
cat QUICKSTART.md
# View the structured catalog
cat catalog.json
```
**Documentation:**
- [`servers/README.md`](servers/README.md) - Complete server collection documentation
- [`servers/QUICKSTART.md`](servers/QUICKSTART.md) - Quick start guide with common use cases
- [`servers/catalog.json`](servers/catalog.json) - Structured server index for programmatic discovery
- Category-specific READMEs in `servers/official/`, `servers/archived/`, and `servers/community/`
### Adding New MCP Servers
```typescript
// In src/mcp_client/McpClient.ts
async addServer(config: MCPServerConfig): Promise<void> {
const client = new Client({
name: config.name,
version: '1.0.0'
}, {
capabilities: { tools: {} }
});
const transport = new StdioClientTransport({
command: config.command,
args: config.args
});
await client.connect(transport);
// Discover and register tools
const tools = await client.listTools();
tools.forEach(tool => this.registerTool(tool));
}
```
**Example configurations for servers from the collection:**
```typescript
// Filesystem server (official)
await this.addServer({
name: 'filesystem',
command: 'npx',
args: ['@modelcontextprotocol/server-filesystem', '/workspace', '/skills']
});
// MongoDB server (community)
await this.addServer({
name: 'mongodb',
command: 'npx',
args: ['-y', 'mongodb-mcp-server', '--readOnly'],
env: { MDB_MCP_CONNECTION_STRING: process.env.MONGODB_URI }
});
// Git server (official)
await this.addServer({
name: 'git',
command: 'npx',
args: ['mcp-server-git']
});
```
### Custom PII Patterns
```typescript
// In your code
const piiCensor = new PiiCensor();
piiCensor.addPattern('custom_id', /\bID-\d{6}\b/g);
```
### Alternative Sandbox Implementations
Extend `SandboxManager` to create custom execution environments:
- WebAssembly-based sandboxes
- Cloud function execution
- Process-based isolation
## 🧪 Testing
```bash
# Test the sandbox
curl -X POST http://localhost:3000/task \
-H "Content-Type: application/json" \
-d '{
"userId": "test",
"task": "Write a simple hello world function and save it to skills"
}'
# Check health
curl http://localhost:3000/health
```
## 📖 Documentation & References
### Core Documentation
- **[PHILOSOPHY.md](docs/PHILOSOPHY.md)** - ⭐ **Start here!** Explains the "why" behind code execution, token efficiency, and design principles based on Anthropic's research
- **[QUICK_START.md](docs/QUICK_START.md)** - Get running in 5 minutes
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical deep dive into system components
- **[SECURITY.md](docs/SECURITY.md)** - Security best practices and hardening checklist
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Production deployment guides (Docker, K8s, Cloud)
- **[API_EXAMPLES.md](docs/API_EXAMPLES.md)** - Usage examples and patterns
### Skills & Examples
- **[skills/examples/](skills/examples/)** - Example skills following the Anthropic skills pattern
- `template-skill/` - Template for creating new skills
- `data-processor/` - Token-efficient data transformation example
### External References
1. **[Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)** - Anthropic's engineering blog post describing the dynamic execution model and philosophy
2. **[Anthropic Skills Repository](https://github.com/anthropics/skills)** - Open-source examples of skills that extend agent capabilities
3. **[Equipping Agents for the Real World with Agent Skills](https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)** - Philosophy behind persistent agent capabilities
4. **[Model Context Protocol Documentation](https://modelcontextprotocol.io)** - MCP specification and guides
5. **[Docker Security Best Practices](https://docs.docker.com/engine/security/)** - Container security hardening
## 🤝 Contributing & Community Collaboration
This is a template repository that represents a **new paradigm** in AI agent development - one where code execution, security, and persistent capabilities work together seamlessly. We believe this approach has the potential to transform how AI agents are built and deployed at scale.
### We're Inviting You to Build This Together
The open-source community is fundamental to advancing this paradigm. We welcome contributions in all forms:
#### **Areas We're Looking For Help**
1. **LLM Integrations** - Add support for more providers (Claude, GPT-4, Gemini, Llama, etc.)
2. **MCP Server Connectors** - Build adapters for popular services (databases, APIs, file systems)
3. **Security Hardening** - Audit the sandbox, propose additional security measures
4. **Performance Optimizations** - Container pooling, caching strategies, resource tuning
5. **Monitoring & Observability** - Prometheus metrics, logging, distributed tracing
6. **Skills Library** - Create reusable, domain-specific skills for the community
7. **Documentation** - Tutorials, deployment guides, best practices
8. **Testing & Examples** - Integration tests, real-world use cases, benchmarks
9. **Alternative Sandboxes** - WebAssembly, cloud functions, process isolation implementations
10. **Frontend UI** - Dashboard, skill explorer, task monitoring interface
#### **How to Contribute**
1. **Fork & Customize** - Start with this template for your specific use case
2. **Share Improvements** - Submit PRs with general-purpose enhancements
3. **Build Skills** - Create reusable skills and submit to the community skills library
4. **Report Issues** - Help us identify bugs and security concerns
5. **Discuss Ideas** - Join conversations about the architecture and design
6. **Write Documentation** - Help others understand and adopt the pattern
#### **The Vision**
We're building toward a future where:
- 🧠 **AI agents scale** beyond token limitations through code execution
- 🔄 **Skills accumulate** over time, making agents continuously smarter
- 🔒 **Privacy is built-in** with automatic PII protection
- 🛡️ **Security is layered** with multiple defense mechanisms
- 🌐 **Tools are discovered dynamically**, not statically configured
- 📚 **Community-driven** with shared skills and best practices
### Customization Guide for Your Organization
Customize this template for your specific needs:
1. **Implement your LLM integration** - Choose your preferred provider
2. **Connect your MCP servers** - Wire up your tools and data sources
3. **Customize security policies** - Adjust for your threat model
4. **Extend PII detection** - Add patterns for your domain
5. **Add monitoring and logging** - Integrate with your observability stack
6. **Build domain-specific skills** - Create your organization's capability library
7. **Share back** - Contribute generic improvements to help the community
### Community Resources
- **Issues & Discussions** - Ask questions, propose features, discuss architecture
- **Skills Repository** - Contribute reusable skills to `skills/examples/`
- **Documentation** - Help improve guides and examples
- **Partnerships** - Collaborate on larger initiatives
### Recognition
Contributors will be recognized in:
- Project README
- Release notes
- Community Hall of Fame
- Speaking opportunities at community events
---
**Together, we can build the next generation of AI agent infrastructure.** Whether you're an AI researcher, DevOps engineer, security expert, or full-stack developer, there's a place for your contributions. Join us in advancing this paradigm!
## 📝 License
MIT License - See LICENSE file for details
## ⚠️ Important Notes
- **TODO Items**: Search for `TODO` comments in the code for areas requiring implementation
- **Security**: Review and harden security settings before production deployment
- **LLM Integration**: The LLM calling function is a placeholder - implement with your provider
- **MCP Servers**: Mock implementations are provided - replace with actual MCP connections
- **Production Ready**: Additional hardening required for production use (monitoring, error handling, scaling)
---
Built with the Code Execution with MCP pattern for dynamic, secure AI agent workflows.
