Structured reference for AI agents operating MCPWorks. Optimized for system-prompt consumption and AI search engines.

---

Platform Summary

MCPWorks is a serverless Python and TypeScript function platform managed and executed via the MCP protocol. Two endpoints per namespace: a create endpoint for CRUD and agent management (25+ tools), a run endpoint for execution. Python sandboxes include 59+ pre-installed packages. TypeScript functions run on Node.js 20+. No pip install or npm install at runtime.

---

MCP Configuration

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

Replace {ns} with the namespace name and {API_KEY} with the bearer token. Subdomain routing ({ns}.create.mcpworks.io) is also supported on Cloud Pro and above.

---

Endpoints

Endpoint	Pattern	Purpose	Metered
Create	api.mcpworks.io/mcp/create/{ns}	Namespace/service/function/agent CRUD	No
Run (code mode)	api.mcpworks.io/mcp/run/{ns}	Single execute tool, write Python or TypeScript	Yes
Run (tool mode)	api.mcpworks.io/mcp/run/{ns}?mode=tools	One tool per function	Yes

Default run mode is code (no query param needed).

---

Create Endpoint — 25+ Tools

Namespace Tools

Tool	Required Params	Optional Params	Notes
make_namespace	name	description	Name: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
list_namespaces	—	—	Returns all namespaces for account

Service Tools

Tool	Required Params	Optional Params	Notes
make_service	name	description	Created in current namespace
list_services	—	—	Returns name, description, function_count, call_count
delete_service	name	—	Deletes all functions in service

Function Tools

Tool	Required Params	Optional Params	Notes
make_function	service, name, backend	code, config, input_schema, output_schema, description, tags, requirements, template	template overrides code/schemas/reqs as defaults
update_function	service, name	backend, code, config, input_schema, output_schema, description, tags, requirements, restore_version	Code/config/schema/req changes create new version
delete_function	service, name	—	Permanent deletion
list_functions	service	tag	Returns qualified names (service.function)
describe_function	service, name	—	Full details + version history

Discovery Tools

Tool	Required Params	Notes
list_packages	—	59 packages grouped by category
list_templates	—	5 templates: hello-world, csv-analyzer, api-connector, slack-notifier, scheduled-report
describe_template	name	Returns code, schemas, requirements

Agent Management Tools

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

Agent Configuration Tools

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

Agent Operation Tools

Tool	Required Params	Optional Params	Notes
add_schedule	name, function_name, cron_expression	mode, failure_policy	Add cron schedule
add_webhook	name, path	—	Add webhook endpoint
chat_with_agent	name, message	replica	Send message to agent
get_agent_state	name, key	—	Read persistent state
set_agent_state	name, key, value	—	Write persistent state
delete_agent_state	name, key	—	Delete persistent state
lock_function	service, name	—	Lock function from modification
unlock_function	service, name	—	Unlock function

---

Run Endpoint

Tool Mode (?mode=tools)

Each function becomes one MCP tool named service.function. Input schema comes from the function's input_schema. AI calls functions directly.

Code Mode (default)

Single tool: execute(code: str). The platform generates a functions/ package from namespace functions.

Discover functions (Python):

import functions
print(functions.__doc__)

Call a function (Python):

from functions import my_func
result = my_func(param="value")

Call a function (TypeScript):

const { my_func } = require("./functions");
const result = my_func({ param: "value" });

Return data: Python: set result = ... (or output = ...). TypeScript: return from main() or module.exports.main.

---

Function Code Conventions

Python

Three ways to return output (checked in order):

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

input_data dict is always available as a global.

TypeScript

Export a main function:

• export default function main(input) { return {...}; }
• module.exports.main = function(input) { return {...}; }

---

Backend Values

Backend	Status	Description
code_sandbox	Active	Secure Python and TypeScript execution (nsjail)

---

Templates

Name	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 Rules

• 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 code into a new version
• All versions are immutable

---

Tier Limits

Subscription Tiers

Tier	Monthly	Executions/mo	Agents
14-Day Pro Trial	$0	125,000	5
Pro	$179	250,000	5
Enterprise	$599	1,000,000	20
Dedicated	$999	Unlimited	Unlimited

Rate Limits

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

Sandbox Resources (per execution)

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

Quota exceeded returns HTTP 429 QUOTA_EXCEEDED.

---

Naming Constraints

Entity	Rules
Namespace	^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ — DNS-compliant, 1-63 chars
Service	String, no special constraints beyond non-empty
Function	String, hyphens converted to underscores in code-mode imports

---

Package 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

Aliases: bs4 = beautifulsoup4, yaml = pyyaml, dateutil = python-dateutil, slugify = python-slugify, sklearn = scikit-learn, PIL = pillow, jwt = pyjwt, psycopg2 = psycopg2-binary

---

Decision Tree: Code Mode vs Tool Mode

Is the AI chaining multiple functions or doing data transformation?
  YES → code mode (default)
  NO →
    Does the AI need to call a single function with structured params?
      YES → tool mode (?mode=tools)
      NO → code mode (default)

Code mode is the default and handles all use cases. Tool mode is useful when the AI should call functions one-at-a-time with schema-validated inputs.

---

Common Patterns

Create namespace, service, function, and execute

1. make_namespace(name="acme")
2. make_service(name="tools")
3. make_function(service="tools", name="hello", backend="code_sandbox", template="hello-world")
4. (switch to run endpoint)
5. execute(code='from functions import hello; result = hello(name="World")')

Update function code

update_function(service="tools", name="hello", code="def main(input_data): ...")

Roll back a function

describe_function(service="tools", name="hello")  # check version history
update_function(service="tools", name="hello", restore_version=1)

Use packages

make_function(
  service="data", name="analyze",
  backend="code_sandbox",
  requirements=["pandas", "numpy"],
  code="import pandas as pd\nimport numpy as np\ndef main(input_data): ...",
  input_schema={...}
)

---

Anti-Patterns

Don't	Do Instead
pip install in function code	Declare in requirements field
Use os.system / subprocess	These are blocked by seccomp
Return large binary data	Return references or summaries
Hardcode API keys in function code	Use required_env / optional_env fields
Create functions without input_schema	Always define schemas for better AI discovery

---

Error Reference

Error	Cause	Fix
QUOTA_EXCEEDED (429)	Monthly execution limit hit	Upgrade tier or wait for reset
Unknown template: X	Invalid template name	Use list_templates to see valid names
Package 'X' is not in the allowed list	Invalid requirement	Use list_packages to see allowed packages
Execution timed out	Code exceeded tier timeout	Optimize code or upgrade tier
No code provided	Empty code in execute/make_function	Provide code or use a template
Invalid tool name format	Tool mode name missing .	Use service.function format
Authentication failed	Bad or missing API key	Check Authorization header
INVALID_HOST	Wrong endpoint format	Use api.mcpworks.io/mcp/{create|run}/{ns}

---

Agent Clusters

Scale any agent to N replicas: scale_agent(name, replicas). Each replica gets full tier resources and a unique verb-animal name.

Tool	Required Params	Notes
scale_agent	name, replicas	Each replica = 1 agent slot. Set replicas=0 to stop all.

Schedule modes (on add_schedule):

• mode: "single" (default) — exactly one replica executes
• mode: "cluster" — all replicas execute independently

Chat affinity: chat_with_agent(name, message, replica="daring-duck") routes to a specific replica. Omit replica for any available.

Scale-down: LIFO (newest removed first).

---

Agent Security

Agents cannot call function management tools during orchestration: make_function, update_function, delete_function, make_service, delete_service, lock_function, unlock_function. Only users via the create endpoint can author functions.

All function output is scanned for leaked secrets (API keys, tokens, connection URIs) before reaching the AI context. Detected values are redacted with [REDACTED_*] markers.

---

Auth Flow

1. Register: POST /v1/auth/register (email, password, name, accept_tos)
2. Login: POST /v1/auth/login returns JWT tokens
3. Create API key: POST /v1/auth/api-keys (requires JWT)
4. Use API key in MCP: Authorization: Bearer {raw_key}

API keys can also be exchanged for JWTs via POST /v1/auth/token.