← All Docs

MCP Server

Tool Reference: External

The external endpoint is for desktop coding agents (Claude Code, Codex) that bundle locally and upload compiled assets. Source-file mutation tools are deliberately removed from this surface — the agent's local repo is the source of truth, not Webase. upload_build is the canonical write path.

Endpoint: https://www.webase.com/mcp/external/messages

Protocol: JSON-RPC over HTTP using MCP tools/list and tools/call.

Required scopes: app_gen_read for read tools, app_gen_write for write tools, or claudeai for both.

This surface exposes 31 tools. The list is generated from the live tool classes registered to this MCP server, so it always reflects what is actually callable in production.

add_data_field WRITE

Add a field to an existing data model. field_type must be one of: String, Text, Number, Boolean, Date, URL, Photo, File, Collaborator, Attachment, Single Select, Link to Object, Dynamic. For 'Single Select' fields, pass the choices in `options`. For 'Link to Object' fields, pass the target model's id or slug in `related_model_id_or_slug`.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

model_id_or_slug Required string

Data model identifier.

name Required string

Field name (e.g. 'email').

field_type Required string

DataField type, e.g. 'String', 'Number', 'Date'.

label string

Display label. Defaults to the humanized name.

options array

Choices for 'Single Select' fields, e.g. ['Lead','Qualified','Won','Lost']. Ignored for other field types.

related_model_id_or_slug string

Target data model for 'Link to Object' fields. Accepts numeric id or slug; must belong to the same application.

create_app_user WRITE

Create an end-user account for an auth-required Webase app. Use this to seed test users, demo accounts, or hand a specific tester their initial credentials. Returns the user's id/slug/email/name plus the `auth_token` in plaintext — treat the token like a password. The end-user can also self-register through the auto-injected login UI on the preview URL; this tool is for cases when the agent or operator wants to create the account directly.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

email Required string

Email address. Must be unique within the application.

password Required string

Initial password. The user can sign in with this and change it via forgot-password if exposed.

name string

Display name. Surfaces in DataService.getCurrentUser() and in the created_by field of records the user creates.

create_application WRITE

Create an empty Webase app for an external coding agent to populate. Does NOT generate code or features — the caller is responsible for writing source files via update_source_file / bulk_update_source_files. Returns the new app's id, slug, and an empty source-file manifest.

Input schema

name Required string

Human-readable app name. Used to derive the slug.

description string

Short description of what the app does. Stored on the Application record; not sent to any LLM.

theme_id string

Optional design system slug (e.g. 'neo-tokyo'). Omit to use the platform default.

model_id string

Optional default LLM model id stored on the app for in-platform features (chat, evaluation). Has no effect on MCP-driven coding.

is_template boolean

Mark the app as a template. Defaults to false.

build_mode string

How the app gets bundled and served. 'browser_bundler' (default) compiles SourceFiles in the browser via esbuild-wasm. 'external_static' expects the agent to upload pre-built assets via upload_build; in that mode source-file mutation tools become read-only.

auth_required boolean

Enable per-user authentication. When true, Webase auto-injects a login/register/forgot-password gate before the app loads, end-users sign in with their own credentials, and the data API auto-scopes records to whoever created them. Defaults to false (anonymous app, all visitors share state).

create_data_model WRITE

Create a new data model (MongoDB collection) on a Webase app. Optionally seed fields in the same call. Returns the created model and its fields.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

name Required string

Human-readable model name (e.g. 'Contacts'). The slug is derived from this and becomes the MongoDB collection name.

fields array

Optional initial fields to create with the model. field_type must be one of: String, Text, Number, Boolean, Date, URL, Photo, File, Collaborator, Attachment, Single Select, Link to Object, Dynamic. For 'Single Select', set `options: ['Lead','Qualified',...]`. For 'Link to Object', set `related_model_id_or_slug` to a sibling data model on the same application (must already exist — create upstream models first when chaining).

create_record WRITE

Create a record in a Webase app's data model. The `record` object's keys may be either DataField slugs/names or field ids; slug/name keys are translated to field ids before persistence so generated apps see the canonical schema.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

record Required object

Field name/slug → value map. Example: { "name": "Alice", "email": "a@b.com" }.

delete_app_user WRITE Destructive

Delete an end-user account from a Webase app. Records they created remain in the data store with their original created_by reference; only their ability to sign in is removed. Use to clean up test users or revoke access. To list AppUsers first, call list_app_users.

Input schema

application_id_or_slug Required string

App identifier.

app_user_id_or_slug Required string

AppUser identifier (numeric id or slug, both shown in list_app_users output).

delete_data_field WRITE Destructive

Remove a field from a data model. Existing records are not modified; the field key simply stops being part of the schema.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

field_id_or_slug Required string

Field identifier (numeric id or slug).

delete_data_model WRITE Destructive

Delete a data model (and all of its fields) from a Webase app. By default the underlying MongoDB documents are kept; pass drop_collection=true to also delete every record in the collection.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

model_id_or_slug Required string

Data model identifier.

drop_collection boolean

If true, also drop the MongoDB collection (deletes every record). Defaults to false.

delete_record WRITE Destructive

Delete a record from a Webase app's data model. Triggers linked-object cleanup interceptors.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

document_id Required string

MongoDB document id (as a string).

deploy_application WRITE

Deploy a Webase app to its Netlify site. Requires that the app has been bundled at least once. Returns the netlify_url and deployed_at timestamp.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

evaluate_application WRITE

Run a quality evaluation on a Webase app. Checks per-requirement compliance and returns a score (0-100, pass threshold 70) plus a structured result. Evaluations do not consume message credits.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

get_application READ

Fetch a Webase app by id or slug. Returns app metadata, deployment info, source-file manifest (filenames + sizes only), and the latest evaluation summary. Use get_source_file to read individual file contents.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

get_data_model READ

Fetch a single data model in a Webase app, including its fields.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

model_id_or_slug Required string

Data model identifier. Accepts the numeric id or the slug.

get_evaluation READ

Fetch a single Webase app evaluation by id, including the full structured result (per-requirement checks, runtime issues, summary, score).

Input schema

evaluation_id Required integer

Numeric id of the evaluation to fetch.

get_preview_url READ

Return the public preview URL for a Webase app plus the status of its latest server-side bundle compilation. Bundling runs asynchronously after every source-file edit, so the preview URL is self-healing: visitors who arrive while a build is in flight see a loading screen that auto-refreshes when the bundle completes. You can safely tell the user the preview URL is live after writing source files — they don't need to wait for the bundle. Inspect `ready` and `last_compile` in the response if you want to confirm or surface a build failure.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

get_record READ

Fetch a single record from a Webase app's data model by its document id. By default returns the raw document keyed by field id; pass humanize_keys=true to swap in field names.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

document_id Required string

MongoDB document id (as a string).

humanize_keys boolean

If true, replace field ids with field names in the returned document. Defaults to false.

get_runtime_constraints READ

Returns the platform conventions a Webase app must follow: entry-point candidates, the React/esm.sh import map, Tailwind CDN rules, HashRouter requirement, the data API URL shape, dark-mode pattern, build-mode comparison. Read this BEFORE generating any source files for a build_mode='browser_bundler' app — violating the constraints will produce a non-bundleable or broken app. For build_mode='external_static' apps you have full freedom (Vite, Next, etc.); only the data API and preview URL sections apply.

Input schema

This tool takes no arguments.

get_source_file READ

Read the contents of a single source file in a Webase app. Use get_application first to see the file manifest and pick a filename. For external_static apps, reads from the active build (or a specific build via build_id).

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

filename Required string

Exact filename/path within the app, as listed in get_application's source_files manifest.

build_id integer

(external_static only) Read from a specific build instead of the active one.

list_app_users READ

List end-users registered with an auth-required Webase application. Returns id, slug, email, name, and timestamps for each AppUser. Useful for verifying that registration is working, debugging which user owns which records, or seeding state from elsewhere. AppUser is distinct from Webase platform users — it's the end-user of a generated app.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

list_applications READ

List the current user's Webase apps (id, slug, name, status, model, timestamps). Use this before selecting an app to inspect or modify.

Input schema

This tool takes no arguments.

list_builds READ

List builds for an external_static Webase app, newest first. Each entry includes status (active|superseded|pending), uploaded_at, asset and source-file counts, and byte sizes. Use this to find a build_id to roll back to or to inspect history.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

limit integer

Max number of builds to return. Defaults to 25.

list_data_models READ

List the data models (collections) defined for a Webase app, including each model's fields. Field types include: String, Text, Number, Boolean, Date, URL, Photo, File, Collaborator, Attachment, Single Select, Link to Object, Dynamic.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

list_evaluations READ

List recent quality evaluations for a Webase app, newest first. Each entry includes status (passed/failed/running) and score (0-100, pass threshold 70).

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

limit integer

Maximum number of evaluations to return. Defaults to 10.

list_records READ

List records in a Webase app's data model. By default returns raw documents keyed by field id (the canonical storage form, what the generated app reads). Pass humanize_keys=true to return documents keyed by field name instead — useful when you're displaying or summarizing data without first calling list_data_models.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

humanize_keys boolean

If true, replace field ids with field names in returned documents. Defaults to false (raw storage form).

list_source_files READ

List all source files in a Webase app. By default returns filename + byte_size only; pass include_content=true to inline file contents (use carefully on large apps). For external_static apps, returns the source-file snapshot of the active build (or a specific build via build_id).

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

include_content boolean

If true, include each file's full content. Defaults to false (manifest only).

build_id integer

(external_static only) Read source from a specific build instead of the active one.

rollback_build WRITE

Activate a previous build for an external_static Webase app. Marks the target build as active and the currently-active build as superseded. Useful for reverting after a bad upload — /preview/:slug serves the rolled-back build immediately.

Input schema

application_id_or_slug Required string

App identifier.

build_id Required integer

Numeric id of the build to activate. Use list_builds to find it.

update_application WRITE

Update Webase app metadata (name, description, theme, default model, is_template flag, auth_required). Does not touch source files. WARNING: setting `auth_required: false` on an app that already has registered AppUsers will make every user-scoped record visible to anyone who opens the preview URL — only flip it off if you understand the consequence.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

name string

New human-readable app name. May change the slug.

description null | string

New description. Pass an empty string to clear.

theme_id string

New design system slug.

model_id string

New default LLM model id used by in-platform features.

is_template boolean

Whether the app is a template.

auth_required boolean

Enable or disable per-user auth. See warning above before turning OFF.

update_data_field WRITE

Update a field on a data model. Supports rename, label/type change, Single Select `options`, and the Link-to-Object target via `related_model_id_or_slug`.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

field_id_or_slug Required string

Field identifier (numeric id or slug).

name string

New field name.

label string

New display label.

field_type string

New DataField type.

options array

New choices for 'Single Select' fields. Pass an empty array to clear.

related_model_id_or_slug string

Target data model for 'Link to Object' fields (id or slug, same application).

update_data_model WRITE

Rename a data model. Note: changing the name regenerates the slug, which renames the underlying MongoDB collection lookup — existing records remain in the old collection.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

model_id_or_slug Required string

Data model identifier.

name Required string

New model name.

update_record WRITE

Update a record in a Webase app's data model. Field name/slug keys in `record` are translated to field ids.

Input schema

application_id_or_slug Required string

App identifier.

model_id_or_slug Required string

Data model identifier.

document_id Required string

MongoDB document id (as a string).

record Required object

Partial or full field map to apply. Keys may be field names/slugs or field ids.

upload_build WRITE

Upload a compiled build (and optional source snapshot) for a Webase app whose build_mode is 'external_static'. The build_tarball must be a base64-encoded tar.gz containing index.html plus any compiled assets, all rooted at the tarball top level (e.g. produced by `tar -cz -C dist .`). The optional source_tarball is a base64-encoded tar.gz of the agent's source tree; common build/cache directories and secret patterns are filtered server-side. Both tarballs are persisted atomically as one Build; the new build immediately becomes active and the previous active build is marked superseded.

Input schema

application_id_or_slug Required string

App identifier. Accepts the numeric id or the friendly slug.

build_tarball_base64 Required string

Base64-encoded tar.gz of the compiled bundle. Must contain an index.html at the root.

source_tarball_base64 string

Base64-encoded tar.gz of the source tree. If omitted, the previous build's source snapshot is carried forward.

activate boolean

Whether to mark the new build as active immediately. Defaults to true.

Typical session

tools/call get_runtime_constraints                              # learn the rules
tools/call create_application      { name: "...",
                                     build_mode: "external_static" }
tools/call create_data_model       { ... }                      # optional, uses MongoDB

# Code locally with any toolchain, run `npm run build`, then:
tools/call upload_build            { build_tarball_base64: ...,
                                     source_tarball_base64: ... }

tools/call get_preview_url         { ... }                      # /preview/<slug> immediate
tools/call list_builds             { ... }                      # browse build history
tools/call rollback_build          { build_id: ... }            # one-click rollback
tools/call deploy_application      { ... }                      # publish to Netlify

See Quick Start for the full coding-agent walkthrough including the tarball commands.