MCPWorks Platform Guide

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 pair of API paths:

api.mcpworks.io/mcp/create/myns — management
api.mcpworks.io/mcp/run/myns — execution

Subdomain routing (myns.create.mcpworks.io) is also supported on Cloud Pro and above.

Namespace names must be 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 a 14-day Pro trial with 125,000 executions — no credit card required.

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://api.mcpworks.io/mcp/create/myns",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    },
    "myns-run": {
      "type": "http",
      "url": "https://api.mcpworks.io/mcp/run/myns",
      "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 — `api.mcpworks.io/mcp/create/{namespace}`

Management operations. Use this to:

Create/list/delete namespaces, services, and functions
Create, configure, and manage autonomous agents
Browse available packages and templates
Inspect function details and version history

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

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

Function execution. Operates in two modes:

Mode	URL	Tools Exposed	Use Case
Code mode (default)	`.../mcp/run/{ns}` or `.../mcp/run/{ns}?mode=code`	Single `execute` tool	Write Python or TypeScript that imports and calls your functions
Tool mode	`.../mcp/run/{ns}?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 25+ tools for managing your functions and agents.

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.

Agent Management

make_agent — Create an autonomous agent. Required: name. Optional: description.
list_agents — List all agents. No parameters.
describe_agent — Get agent details. Required: name.
start_agent — Start an agent. Required: name.
stop_agent — Stop an agent. Required: name.
destroy_agent — Permanently delete an agent. Required: name.
clone_agent — Clone an agent. Required: name, new_name.
scale_agent — Scale agent replicas. Required: name, replicas.

Agent Configuration

configure_agent_ai — Set AI provider and model. Required: name, provider, model, api_key.
remove_agent_ai — Remove AI configuration. Required: name.
configure_mcp_servers — Attach MCP servers to agent. Required: name, servers.
configure_orchestration_limits — Set iteration/token/time limits. Required: name. Optional: max_iterations, max_ai_tokens, max_execution_time, max_functions_called.

Agent Operations

add_schedule — Add cron schedule. Required: name, function_name, cron_expression.
add_webhook — Add webhook endpoint. Required: name, path.
chat_with_agent — Send message to agent. Required: name, message.
get_agent_state / set_agent_state / delete_agent_state — Manage persistent state.
lock_function / unlock_function — Lock/unlock functions from modification.

Writing Function Code

Python

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

Define a main(input_data) function that returns a value
Set a result variable
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 required and optional environment variables. Use required_env and optional_env in the function schema. Values are passed securely via the X-MCPWorks-Env header and injected into the sandbox at runtime.

Billing & Tiers

Subscription Tiers

Tier	Monthly	Executions/mo	Agents	Sandbox Timeout	Sandbox Memory
14-Day Pro Trial	$0	125,000	5	90s	512 MB
Pro	$179	250,000	5	90s	512 MB
Enterprise	$599	1,000,000	20	300s	2 GB
Dedicated	$999	Unlimited	Unlimited	300s	2 GB

Rate Limits

Metric	Pro Trial	Pro	Enterprise	Dedicated
Executions/min	100	100	300	500
Concurrent	15	15	50	100

New accounts start on the 14-day Pro trial. 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 (125000) exceeded",
  "usage": 125000,
  "limit": 125000,
  "tier": "pro_trial"
}

Usage resets at the start of each calendar month.

Sandbox Limits

Resource limits scale by subscription tier:

Resource	Pro Trial / Pro	Enterprise / Dedicated
Timeout	90s	300s
Memory	512 MB	2 GB

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

The platform generates a functions/ package from your namespace's functions (Python module or TypeScript/Node require)
Your code can import from this package
Each function wrapper calls the actual function code internally
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

Agent Security

Agents Cannot Author Functions

During AI orchestration (schedules, webhooks, heartbeats, chat), agents cannot call function management tools: make_function, update_function, delete_function, make_service, delete_service, lock_function, unlock_function.

Only users with access to the create MCP endpoint can author functions. This prevents prompt injection attacks from tricking an agent into writing code that exfiltrates credentials.

Output Secret Scanner

All function output is scanned for leaked credentials before reaching the AI context:

Known patterns: Stripe keys, OpenAI keys, Slack tokens, AWS keys, GitHub/GitLab tokens, JWTs, database URIs, private keys
Env var values: exact matches of values passed via the X-MCPWorks-Env header (8+ characters)

Detected secrets are replaced with [REDACTED_*] markers. A security event is logged with the function name and detection type — the actual secret value never appears in the log.

Core Concepts

Namespaces

Services

Functions

Versions

Backends

Getting Started

1. Create Your Account

2. Get Your API Key

3. Connect Your AI Assistant

4. Create a Service and Function

5. Execute It

Two Endpoints

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

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

Create Endpoint Tools

Namespace Management

Service Management

Function CRUD

Discovery

Agent Management

Agent Configuration

Agent Operations

Writing Function Code

Python

TypeScript

Available Packages

Python

TypeScript / Node.js

Templates

Versioning

Environment Variables

Billing & Tiers

Subscription Tiers

Rate Limits

Quota Enforcement

Sandbox Limits

Code Mode Deep Dive

How It Works

Discovering Functions

Calling Functions

Returning Data

Why Code Mode Saves Tokens

End-to-End Examples

Example 1: Create and Execute a Simple Function

Example 2: Using a Template

Example 3: Code Mode with Multiple Functions

Example 4: Version Rollback

Agent Clusters

Schedule Modes

Chat Session Affinity

Scale Down

Agent Security

Agents Cannot Author Functions

Output Secret Scanner

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

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