MCP Server (Hosted)

The ERA Agent provides a hosted MCP server that allows Claude Desktop and other MCP clients to execute code in secure, isolated environments. This is perfect for AI assistants that need to run code, analyze data, or perform computational tasks.

Quick Start

Connect with Claude Desktop

Add the following configuration to your Claude Desktop settings:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "era-agent": {
      "url": "https://anewera.dev/mcp/v1"
    }
  }
}

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "era-agent": {
      "url": "https://anewera.dev/mcp/v1"
    }
  }
}

Linux

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "era-agent": {
      "url": "https://anewera.dev/mcp/v1"
    }
  }
}

Using Your Own Deployment

Replace https://anewera.dev with your own Cloudflare Worker URL after deploying.

Restart Claude Desktop

After updating the configuration, restart Claude Desktop completely. The ERA Agent tools will now be available in your conversations.

Available Tools

The MCP server provides 14 tools for code execution and session management:

Language-Specific Quick Execution Tools

These tools provide the easiest way to run code without managing sessions:

era_python

Execute Python code with a single command.

Claude Usage:

Run this Python FizzBuzz:
for i in range(1, 16):
    if i % 15 == 0:
        print(f'{i}: FizzBuzz')
    elif i % 3 == 0:
        print(f'{i}: Fizz')
    elif i % 5 == 0:
        print(f'{i}: Buzz')
    else:
        print(f'{i}: {i}')

Features:

• Automatic Python 3 execution
• Handles complex code (f-strings, loops, classes)
• Clean output capture
• Internet access enabled by default

era_node

Execute Node.js/JavaScript code.

Claude Usage:

Run this in Node.js:
const data = [1, 2, 3, 4, 5];
console.log('Sum:', data.reduce((a, b) => a + b));
console.log('Average:', data.reduce((a, b) => a + b) / data.length);

era_typescript

Execute TypeScript with type checking.

Claude Usage:

Run this TypeScript code:
interface User {
  name: string;
  age: number;
}

const user: User = { name: 'Alice', age: 30 };
console.log(`${user.name} is ${user.age} years old`);

era_deno

Execute code with Deno runtime.

Claude Usage:

Run this with Deno:
const text = await Deno.readTextFile('/etc/hosts');
console.log('First 5 lines:', text.split('\n').slice(0, 5));

era_shell

Execute shell commands for system operations.

Claude Usage:

Run these shell commands:
- Check Python version: python3 --version
- Install packages: pip install pandas numpy
- List directory: ls -la

Common Uses:

• Package installation: pip install requests, npm install lodash
• Environment setup: apt-get update && apt-get install -y git
• File operations: mkdir data && cd data && wget [url]
• System info: uname -a, df -h, free -m

Core Execution Tools

1. era_execute_code

Execute code in an ephemeral environment. The environment is automatically cleaned up after execution.

Parameters:

• code (string, required): The code to execute
• language (string, required): Programming language - python, node, typescript, go, or deno
• files (object, optional): Files to create before execution (filename → content)
• envs (object, optional): Environment variables
• timeout (number, optional): Execution timeout in seconds (default: 30)
• allowInternetAccess (boolean, optional): Allow internet access (default: true)

Example:

Can you calculate the first 10 Fibonacci numbers using Python?

2. era_create_session

Create a persistent execution session. Sessions maintain state across multiple code executions.

Parameters:

• language (string, required): Programming language for the session
• persistent (boolean, optional): Enable file persistence (default: false)
• allowInternetAccess (boolean, optional): Allow internet access (default: true)
• default_timeout (number, optional): Default timeout for executions in this session

Example:

Create a Python session so we can work on a data analysis project together.

3. era_run_in_session

Execute code in an existing session. State is maintained between executions.

Parameters:

• session_id (string, required): Session ID from era_create_session
• code (string, required): Code to execute
• timeout (number, optional): Execution timeout in seconds
• env (object, optional): Environment variables for this execution

Example:

First, define x = 5. Then in the next execution, print x * 2.

4. era_list_sessions

List all active sessions.

Example:

Show me all my active coding sessions.

5. era_get_session

Get details about a specific session.

Parameters:

• session_id (string, required): Session ID to query

6. era_delete_session

Delete a session and clean up its resources.

Parameters:

• session_id (string, required): Session ID to delete

Example:

Delete the Python session we created earlier.

7. era_update_session

Update session configuration like timeout and network access settings.

Parameters:

• session_id (string, required): Session ID to update
• default_timeout (number, optional): Default timeout in seconds for all runs
• allowInternetAccess (boolean, optional): Enable/disable outbound requests
• allowPublicAccess (boolean, optional): Enable/disable inbound proxy requests

Example:

Update the Python session to extend timeout to 10 minutes for long-running tasks.

Example:

Disable internet access for security reasons in the session.

Use Cases:

• Extend timeout when tasks take longer than expected
• Toggle network access based on security requirements
• Adjust settings between different phases of a workflow

8. era_upload_file

Upload a file to a session workspace.

Parameters:

• session_id (string, required): Target session ID
• path (string, required): File path in the session workspace
• content (string, required): File content

Example:

Upload a CSV file with this data to the session.

9. era_read_file

Read a file from a session workspace.

Parameters:

• session_id (string, required): Source session ID
• path (string, required): File path to read

Example:

Show me the contents of results.txt from the session.

10. era_list_files

List all files in a session workspace.

Parameters:

• session_id (string, required): Session ID to query

Example:

What files are in the session?

Example Conversations

Quick Calculation

You: Can you calculate the sum of squares from 1 to 100 in Python?

Claude: I'll use the era_execute_code tool to calculate that.
[Executes Python code]
The sum of squares from 1 to 100 is 338,350.

Data Analysis Session

You: Let's analyze some data. Create a Python session with pandas.

Claude: I'll create a persistent Python session for our analysis.
[Creates session]

You: Load this CSV data: [paste data]

Claude: I'll upload the CSV to the session.
[Uploads file]

You: Now calculate the mean of column 'sales'

Claude: I'll read the CSV and calculate the mean.
[Runs code in session]
The mean sales value is $45,230.

Multi-Language Development

You: Test this JavaScript function and then write a Go version.

Claude: I'll test the JavaScript first.
[Executes Node.js code]

Now let me write and test the Go version.
[Executes Go code]

Both versions produce the same output!

Resources

The MCP server also exposes session metadata and files as resources:

Session Metadata

• URI: session://{session_id}
• Returns: JSON with session details (language, creation time, etc.)

Session Files

• URI: session://{session_id}/files
• Returns: List of all files in the session workspace

Architecture

The MCP server is built directly into the Cloudflare Worker alongside the REST API:

Cloudflare Worker
├── /api/* → REST API (direct HTTP access)
├── /mcp/v1 → MCP Server (JSON-RPC 2.0)
└── Both share:
    ├── Durable Objects (session state)
    ├── R2 Storage (file persistence)
    └── Container runtime (code execution)

Key Benefits:

• Zero latency: MCP calls API functions directly (no HTTP overhead)
• Shared resources: Sessions and files work across both MCP and REST API
• Global edge: Runs on Cloudflare’s global network
• Automatic scaling: Handles any number of concurrent requests

Protocol Details

The MCP server implements the Model Context Protocol specification using JSON-RPC 2.0 over HTTP/HTTPS.

Endpoint

https://anewera.dev/mcp/v1

Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "era_execute_code",
    "arguments": {
      "code": "print('Hello, World!')",
      "language": "python"
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Exit Code: 0\n\nStdout:\nHello, World!\n\nDuration: 24ms"
      }
    ]
  }
}

Differences from Local MCP

Feature	Hosted MCP	Local MCP
Transport	HTTP/HTTPS	stdio
Authentication	Optional (API keys)	None
Deployment	Cloudflare Workers	Local binary
Scaling	Automatic	Single process
State	Durable Objects	BoltDB
Files	R2 Storage	Local filesystem
Setup	URL configuration	Binary + PATH

Testing

You can test the MCP server using the provided test script:

cd cloudflare
./test-mcp.sh

This will test:

• Protocol initialization
• Tool discovery
• Code execution
• Session management
• Resource listing

Troubleshooting

Tools Not Appearing in Claude Desktop

1. Check configuration file location:

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

2. Verify JSON syntax:

   # On macOS/Linux
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq '.'

3. Restart Claude Desktop completely:

   • Quit the application (not just close the window)
   • Reopen Claude Desktop

4. Check the MCP server is running:

   curl -X POST https://anewera.dev/mcp/v1 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","clientInfo":{"name":"test","version":"1.0.0"}}}'

Execution Timeouts

If code execution times out:

• Increase the timeout parameter (default: 30 seconds, max: 300 seconds)
• Check if the code has infinite loops
• Consider breaking long-running tasks into smaller chunks

Session Not Found

Sessions are automatically cleaned up after inactivity:

• Default timeout: 30 minutes
• Save important results before ending the conversation
• Use persistent sessions for longer-running work

Security

Sandboxing

All code executes in isolated Firecracker microVMs:

• No access to other sessions
• Network isolation (unless allowInternetAccess: true)
• Resource limits enforced
• Automatic cleanup after execution

Best Practices

1. Don’t store secrets: Avoid putting API keys or passwords in code
2. Validate inputs: Check data before processing
3. Use sessions wisely: Delete sessions when done to free resources
4. Monitor usage: Check execution logs if you deploy your own instance

Deploying Your Own

To deploy your own MCP server:

cd cloudflare
npx wrangler deploy

Then update your Claude Desktop configuration with your Worker URL:

{
  "mcpServers": {
    "era-agent": {
      "url": "https://your-worker.workers.dev/mcp/v1"
    }
  }
}

Example Workflows

Quick Python Execution

You: “Run this Python code: print([x**2 for x in range(10)])”

Claude: Uses era_python (automatically)

Result:

[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

FizzBuzz with Logging

You: “Write a FizzBuzz in Python and log each step”

Claude: Uses era_python with complete logging code

Result: Full FizzBuzz output with all steps logged

Installing Packages & Data Analysis

You: “Create a Python session, install pandas, and analyze some data”

Claude:

1. Uses era_create_session → Gets session ID
2. Uses era_shell: pip install pandas
3. Uses era_run_in_session to analyze data with pandas

Multi-Language Algorithm Testing

You: “Test quicksort in both Python and JavaScript”

Claude:

1. Uses era_python with quicksort implementation
2. Uses era_node with quicksort implementation
3. Compares results

Web Scraping with Packages

You: “Scrape the top stories from Hacker News”

Claude:

1. Uses era_create_session (network already enabled!)
2. Uses era_shell: pip install requests beautifulsoup4
3. Uses era_run_in_session to scrape and parse HTML

Result: Top stories listed

Code Execution Gotchas & Best Practices

✅ What Works Great

Complex Python Code

Handles f-strings, loops, and complex syntax perfectly:

for i in range(1, 16):
    print(f'{i}: FizzBuzz' if i % 15 == 0 else f'{i}: Fizz' if i % 3 == 0 else i)

Multi-line Code

Newlines and indentation are preserved exactly - no escaping needed.

Special Characters

Single quotes, double quotes, backticks all work in strings.

⚠️ Common Pitfalls

Pitfall 1: Using Generic Tool When Language-Specific Exists

Less Optimal:

Execute this code with language python: print("Hello")

Better:

Use era_python: print("Hello")

Pitfall 2: Installing Packages Mid-Execution

Problem: Code fails if package isn’t installed

Solution: Use era_shell first:

1. Create a Python session
2. Use era_shell: pip install pandas
3. Then run your pandas code

Pitfall 3: Assuming State Between Ephemeral Calls

Problem: Variables don’t persist between separate era_python calls

Solution: Use sessions for stateful work

🎯 Hosted vs Local Differences

Feature	Hosted (This)	Local MCP
Setup	Just add URL	Need Docker/Firecracker
Network	Enabled by default ✅	Disabled by default
State	Durable Objects (cloud)	Local filesystem
Scaling	Automatic	Manual
Configuration	URL only	Binary path + env vars
Internet Access	Always available	Must enable per session

🚀 Performance Tips

Choose the Right Tool

Scenario	Tool	Reason
Single Python script	era_python	Fast, no session overhead
Multiple related runs	Session + era_run_in_session	State persistence
Package installation	era_shell	System-level operations
Web scraping	Session (network included!)	Persistent HTTP connections

Session vs Ephemeral

Use Ephemeral (era_python, etc.):

• Quick calculations
• Independent scripts
• No package dependencies

Use Sessions:

• Installing packages
• Multi-step workflows
• Building on previous state

🛡️ Security & Limits

Internet Access

• Enabled by default (unlike local MCP)
• All network requests allowed
• Perfect for API calls and web scraping

Resource Limits

• CPU: 1 core per execution
• Memory: 256 MiB default
• Timeout: 30 seconds default (configurable)
• Execution: Isolated Firecracker VMs

Cloud Benefits

• Automatic scaling: No infrastructure to manage
• Global deployment: Cloudflare’s edge network
• Persistent state: Sessions survive across requests
• R2 storage: Files persist in cloud storage

Next Steps

• Try the REST API for direct HTTP access
• Learn about session management
• Explore multi-language support
• Check out example projects
• Compare with Local MCP for self-hosted option