MCPWorks is a code execution platform for AI assistants. You create Python or TypeScript functions through the MCP protocol, and AI agents (Claude Code, Codex, GitHub Copilot) can discover and execute them in secure sandboxes.

No servers to manage. No containers to configure. Write a function, and it runs.

---

Core Concepts

Namespaces

A namespace is your top-level organizational unit. Each namespace maps to a subdomain pair:

• myns.create.mcpworks.io — management
• myns.run.mcpworks.io — execution

Namespace names must be DNS-compliant: lowercase alphanumeric with hyphens, 1-63 characters, starting and ending with an alphanumeric character.

Services

Services group related functions within a namespace. Think of them as folders. A namespace can have many services, each with many functions.

Functions

A function is a unit of executable code with:

• Code — Python or TypeScript source
• Language — python or typescript
• Input schema — JSON Schema describing expected parameters
• Output schema — JSON Schema describing the return value
• Backend — execution engine (code_sandbox)
• Requirements — packages needed (Python from allow-list, TypeScript via npm)
• Tags — optional labels for filtering

Versions

Every code change creates a new immutable version. You can restore any previous version. The active version is always the latest.

Backends

Currently supported: code_sandbox (secure Python and TypeScript execution via nsjail).

---

Getting Started

1. Create Your Account

Register at api.mcpworks.io/register with your email. You get 1,000 free function executions per month.

2. Get Your API Key

After registration, log in at api.mcpworks.io/login. From the dashboard, create an API key. The raw key is shown only once — save it.

3. Connect Your AI Assistant

Add this to your project's .mcp.json (or ~/.claude/settings.json for global access):

{
  "mcpServers": {
    "myns-create": {
      "type": "http",
      "url": "https://myns.create.mcpworks.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    },
    "myns-run": {
      "type": "http",
      "url": "https://myns.run.mcpworks.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Replace myns with your namespace name and YOUR_API_KEY with your actual key.

4. Create a Service and Function

Ask your AI assistant:

"Create a service called 'utils' in my MCPWorks namespace, then create a hello-world function using the hello-world template."

5. Execute It

"Run hello-world with name 'MCPWorks'"

---

Two Endpoints

Every namespace gets two MCP endpoints, each serving a different purpose.

Create Endpoint — {namespace}.create.mcpworks.io/mcp

Management operations. Use this to:

• Create/list/delete namespaces, services, and functions
• Browse available packages and templates
• Inspect function details and version history

Not metered. Management calls don't count against your execution quota.

Run Endpoint — {namespace}.run.mcpworks.io/mcp

Function execution. Operates in two modes:

Mode	URL	Tools Exposed	Use Case
Code mode (default)	.../mcp or .../mcp?mode=code	Single execute tool	Write Python or TypeScript that imports and calls your functions
Tool mode	.../mcp?mode=tools	One tool per function	AI calls functions directly by name

Metered. Each execution counts against your monthly quota.

---

Create Endpoint Tools

The create endpoint exposes 13 tools for managing your functions.

Namespace Management

• make_namespace — Create a new namespace. Params: name (required), description (optional).
• list_namespaces — List all namespaces for your account. No parameters.

Service Management

• make_service — Create a new service in the current namespace. Params: name (required), description (optional).
• list_services — List all services. Returns name, description, function_count, call_count.
• delete_service — Delete a service and all its functions. Params: name (required).

Function CRUD

• make_function — Create a new function. Required: service, name, backend. Optional: code, config, input_schema, output_schema, description, tags, requirements, template.
• update_function — Update a function. Creates a new version if code/config/schemas/requirements change. Required: service, name. Optional: all fields plus restore_version.
• delete_function — Delete a function permanently. Required: service, name.
• list_functions — List functions in a service. Required: service. Optional: tag filter.
• describe_function — Get full details including code, schemas, all versions, and metadata. Required: service, name.

Discovery

• list_packages — List all 60+ available Python packages, grouped by category.
• list_templates — List the 5 available function templates.
• describe_template — Get full template details including code and schemas. Required: name.

---

Writing Function Code

Python

Three ways to return output from a Python function (checked in order):

1. Define a main(input_data) function that returns a value
2. Set a result variable
3. Set an output variable

The input_data dict is always available as a global containing the parameters passed to your function.

def main(input_data):
    name = input_data.get("name", "World")
    return {"greeting": f"Hello, {name}!"}

TypeScript

Export a main function as the default export or named export:

export default function main(input: Record<string, any>) {
    const name = input.name ?? "World";
    return { greeting: `Hello, ${name}!` };
}

Or use module.exports:

module.exports.main = function(input) {
    return { greeting: `Hello, ${input.name ?? "World"}!` };
};

---

Available Packages

Python

MCPWorks Python sandboxes come with 59+ pre-installed packages across 13 categories:

Category	Packages
HTTP	requests, httpx, urllib3, aiohttp, websockets
Data formats	pyyaml, orjson, tomli, tomli-w, xmltodict, msgpack
Validation	pydantic, attrs, jsonschema
Text	beautifulsoup4, lxml, markdownify, markdown, html2text, chardet, python-slugify, jinja2, regex
Datetime	python-dateutil, pytz, arrow
Data science	numpy, pandas, scipy, scikit-learn, sympy, statsmodels
Visualization	matplotlib, pillow
AI	openai, anthropic, tiktoken, cohere
Cloud	boto3, stripe, sendgrid, twilio, google-cloud-storage
File formats	openpyxl, xlsxwriter, tabulate, feedparser, python-docx, pypdf
Security	cryptography, pyjwt, bcrypt
Database	psycopg2-binary, pymongo, redis
Utilities	humanize, tqdm, rich, typing-extensions

Common aliases are supported: bs4 for beautifulsoup4, yaml for pyyaml, sklearn for scikit-learn, PIL for pillow, and more.

TypeScript / Node.js

TypeScript functions run on Node.js 20+ with full npm package support. Declare dependencies in the function's requirements field and they are installed at build time.

---

Templates

Five starter templates for common use cases:

Template	Description	Requirements
hello-world	Greet by name, prove system works	—
csv-analyzer	Parse CSV, return summary stats	—
api-connector	Call external API, return response	httpx
slack-notifier	Post to Slack webhook	httpx
scheduled-report	Generate markdown/JSON report	—

Usage: make_function(service="x", name="y", backend="code_sandbox", template="hello-world")

---

Versioning

MCPWorks automatically versions your function code:

• make_function creates v1
• update_function with code/config/schema/requirements changes creates a new version (v2, v3, ...)
• update_function with only description/tags is a metadata update — no new version
• update_function with restore_version=N copies vN into a new version
• All versions are immutable — you can always go back

---

Environment Variables

Functions can declare environment variables via required_env and optional_env schema fields. This is a future feature — environment variables are not yet injected into the sandbox at runtime.

---

Billing & Tiers

Subscription Tiers

Tier	Executions/Month
Free	1,000
Builder	25,000
Pro	250,000
Enterprise	1,000,000

Pricing will be announced before general availability.

New accounts start on the free tier. Each successful tools/call request to the run endpoint counts as one execution. Management operations on the create endpoint are free and unlimited.

Quota Enforcement

When you hit your monthly limit, run endpoint calls return HTTP 429:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly execution limit (1000) exceeded",
  "usage": 1000,
  "limit": 1000,
  "tier": "free"
}

Usage resets at the start of each calendar month.

---

Sandbox Limits

Resource limits scale by subscription tier:

Resource	Free	Builder	Pro	Enterprise
Timeout	10 sec	30 sec	90 sec	300 sec
Memory	128 MB	256 MB	512 MB	2048 MB
Max PIDs	16	32	64	128
Network hosts	0 (none)	5	25	Unlimited

The production sandbox uses nsjail with Linux namespaces, cgroups v2, and seccomp-bpf for isolation. Code size is limited to 1 MB.

---

Code Mode Deep Dive

Code mode is the default run mode. Instead of exposing each function as a separate MCP tool, it exposes a single execute tool that accepts Python or TypeScript code.

How It Works

1. The platform generates a functions/ package from your namespace's functions (Python module or TypeScript/Node require)
2. Your code can import from this package
3. Each function wrapper calls the actual function code internally
4. Return data by setting result = ... in your code

Discovering Functions

import functions
print(functions.__doc__)

This prints a catalog of all functions in the namespace with their signatures and descriptions.

Calling Functions

from functions import hello
result = hello(name="World")

Or import from a specific service module:

from functions.utils import hello, word_count

Function names with hyphens are converted to underscores (my-func becomes my_func).

Returning Data

Set result to whatever you want returned to the conversation:

from functions import analyze_csv, format_report

data = analyze_csv(csv_data="name,age\nAlice,30\nBob,25")
result = format_report(
    title="Analysis",
    sections=[{"heading": "Data", "content": str(data)}]
)

Why Code Mode Saves Tokens

Based on Anthropic's Code Execution MCP research (January 2026), code mode achieves 70-98% token savings compared to traditional MCP tool-per-function approaches. Intermediate data stays in the sandbox and never enters the AI's context window.

---

End-to-End Examples

Example 1: Create and Execute a Simple Function

Step 1: Create a namespace (if you don't have one)

"Create a namespace called 'demo'"

Step 2: Create a service

"Create a service called 'math' in my namespace"

Step 3: Create a function

"Create a function called 'is-prime' that checks if a number is prime"

Step 4: Execute it in code mode

from functions import is_prime
result = is_prime(number=17)

Example 2: Using a Template

"Create a function called 'fetch' in my 'utils' service using the api-connector template"

This clones the template's code, schemas, tags, and requirements (httpx).

Example 3: Code Mode with Multiple Functions

from functions import fetch, analyze_csv

# Fetch CSV from a URL
response = fetch(url="https://example.com/data.csv")

# Analyze it
stats = analyze_csv(csv_data=response["body"])

result = {
    "url": "https://example.com/data.csv",
    "rows": stats["row_count"],
    "columns": stats["columns"],
    "statistics": stats["stats"]
}

Example 4: Version Rollback

"Update my is-prime function to also return the factors if not prime"

Creates version 2.

"Actually, restore the original version"

Calls update_function(service="math", name="is-prime", restore_version=1) — creates version 3 with v1's code.

---

Agent Clusters

Agents can be scaled to N replicas sharing the same configuration. Each replica is an independent container with its own verb-animal name (e.g., "daring-duck", "swift-falcon").

scale_agent(name="social-scraper", replicas=5)

Each replica counts as one agent slot toward your tier limit and gets full tier resources (RAM, CPU).

Schedule Modes

When an agent has multiple replicas, schedule coordination matters:

• single (default) — exactly one replica executes the schedule. No duplicates.
• cluster — all replicas execute the schedule independently.

add_schedule(name="social-scraper", function_name="scrape.sources",
  cron_expression="*/15 * * * *", mode="cluster",
  failure_policy={"strategy": "continue"})

add_schedule(name="social-scraper", function_name="post.daily-summary",
  cron_expression="0 12 * * *", mode="single",
  failure_policy={"strategy": "continue"})

Chat Session Affinity

For multi-turn conversations with a specific replica:

chat_with_agent(name="social-scraper", message="What did you find?")
# Response includes: replica: "daring-duck"

chat_with_agent(name="social-scraper", message="Tell me more", replica="daring-duck")
# Routed to the same replica

Scale Down

Scaling down removes the newest replicas first (LIFO), preserving the oldest replicas and their active chat sessions.

scale_agent(name="social-scraper", replicas=2)
# Removes the 3 newest replicas, keeps the 2 oldest