Skip to main content

MCP Server (BETA)

Beta feature

MCP Server is in beta. Its behavior, available tools, and client configuration may change. If you find an issue or have a suggestion, submit a support ticket and identify the feature as MCP Server (BETA). Never include an MCP key in a support ticket.

Appsmith's Model Context Protocol (MCP) server lets compatible AI clients connect to Appsmith through a structured API. An MCP client can use the Appsmith capabilities available to the user who created its key, including working with apps and their resources.

An MCP key authenticates the client as you. It does not grant the client additional Appsmith permissions. Any request made with your key is limited to the same organizations, workspaces, apps, and actions that your Appsmith account can access.

This guide covers MCP setup for Appsmith Business Cloud and self-hosted Enterprise deployments.

Before you begin​

  • An Appsmith administrator must enable MCP Server for the organization or instance.
  • Each user must create their own MCP key. Do not share a key between users.
  • Your AI client must support a remote MCP server and must be able to send the key as an Authorization header. Appsmith MCP Server authenticates with the key only; it does not offer an OAuth sign-in flow. Clients whose connectors support only OAuth or no authentication, such as ChatGPT conversations, cannot connect. See Client compatibility.

Enable MCP Server​

MCP Server is off by default. The location of the setting depends on your Appsmith deployment.

Business Cloud​

To enable MCP Server for a Business Cloud organization:

  1. Open Admin Settings.
  2. Under Organisation, select MCP Server (BETA).
  3. Turn on Enable MCP server, and save the setting.
MCP Server beta setting under Organisation in Business Cloud
Enable MCP Server for a Business Cloud organization

Self-hosted Enterprise​

To enable MCP Server for a self-hosted Enterprise instance:

  1. Open Admin Settings.
  2. Under Instance, select MCP Server (BETA).
  3. Turn on Enable MCP server.
  4. Click Save & Restart to apply the setting.
MCP Server beta setting under Instance settings in a self-hosted Enterprise instance
Enable MCP Server for a self-hosted Enterprise instance

When MCP Server is disabled, Appsmith removes access to the /mcp endpoint, prevents users from creating or rotating keys, and rejects requests made with existing keys. Disabling the server does not revoke the keys. Revoke a key separately if you want to invalidate it permanently.

Run MCP Server on more than one replica​

On a self-hosted instance that runs two or more Appsmith replicas behind a load balancer, MCP Server shares its sessions through the Redis instance that APPSMITH_REDIS_URL points to, the same Redis that Appsmith already uses for user sessions. Any replica can serve any MCP session, and an approval prompt answered on one replica reaches the replica that asked for it. No additional configuration is required.

MCP clients do not send cookies, so sticky sessions on the load balancer cannot keep an MCP session on one replica. Without the shared session store, a request that reaches a replica other than the one that opened the session fails with HTTP 404, and clients see intermittent errors and missing tool lists.

Keep the following in mind when you run multiple replicas:

  • APPSMITH_REDIS_URL must point to one Redis instance that every replica can reach. See Configure External Redis.
  • If the Redis user has a restricted ACL, grant read and write access to keys that start with appsmith:mcp:, permission to run EVAL (the @scripting category; MCP Server uses two short Lua scripts for entity locks and one-time confirmations), and PUBLISH and SUBSCRIBE access to channels that start with appsmith:mcp:relay:. MCP Server refuses to start if it cannot subscribe, and the container log for the mcp program explains why.
  • Each replica opens two additional Redis connections for MCP Server. Redis is not a credential store: MCP Server never writes a user's MCP key to it, and a session record holds only a hash that binds the session to the key that opened it. Every Redis entry that MCP Server writes, all under the appsmith:mcp: prefix, carries a time to live, so flushing them only drops open MCP sessions, and compliant clients reconnect automatically.
  • During a rolling upgrade to a version that includes the shared store, sessions opened on a replica running the older version fail with HTTP 404 on replicas running the newer version, and the reverse, until the rollout completes. MCP clients reconnect on their own.

Create an MCP key​

After an administrator enables MCP Server, each user can create and manage keys from their own profile:

MCP keys page with How to connect and Create Key buttons
Create and manage personal MCP keys from Profile settings
  1. Open Admin Settings.
  2. Under Profile, select MCP keys.
  3. Click Create Key.
  4. Enter a descriptive name, up to 50 characters, that identifies the client or purpose of the key.
  5. Select how long the key should remain valid: 30, 60, 90, 180, or 365 days. The default is 30 days.
  6. Click Create.
Create Key window with fields for the MCP key name and validity in days
Name the key and choose how long it remains valid

You can have up to 10 MCP keys that have not been revoked. Expired keys count toward this limit, so revoke an unused or expired key before creating another one.

Copy the key and connect your client​

Appsmith shows the key only once, immediately after you create or rotate it. Before closing the confirmation window, copy either the key, labelled MCP token in this window, or the complete client configuration, and store it securely.

MCP token created window with one-time token, server URL, client configuration, and expiration date
Copy the token or client configuration before closing this window

Choose your AI client and add the configuration using the MCP server URL and key from that window. Replace YOUR_APPSMITH_DOMAIN and YOUR_MCP_KEY with those values.

You can return to Profile > MCP keys and click How to connect to copy the server URL and a configuration template, but Appsmith cannot display an existing key again.

  1. Open Cursor Settings → Tools & MCP, or edit the config file:

    • macOS / Linux: ~/.cursor/mcp.json
    • Windows: %USERPROFILE%\.cursor\mcp.json
    • Project-level: .cursor/mcp.json in the project root
  2. Add the Appsmith server:

    {
    "mcpServers": {
    "appsmith": {
    "url": "https://YOUR_APPSMITH_DOMAIN/mcp",
    "headers": {
    "Authorization": "Bearer YOUR_MCP_KEY"
    }
    }
    }
    }
  3. Save the file and restart Cursor if the server does not appear.

This is the same JSON structure Appsmith generates when you create a key.

Protect your key

An MCP key grants the client access as your Appsmith user. Do not commit it to source control, include it in logs, paste it into a support ticket, or share it with another person. Use a separate key for each client, choose the shortest practical validity period, and revoke a key immediately if it might have been exposed.

When MCP JS objects are enabled, an MCP client can read the source of every JS object that the key owner can access, including JS objects written in the editor. Secrets typed into that code, such as API keys or passwords, are returned to the client as written. Keep secrets in datasource configuration instead of in JS code.

Client compatibility​

Appsmith MCP Server authenticates every request with the MCP key sent as a bearer token. It does not provide an OAuth authorization server, so a client can connect only if it can send the key in an Authorization header or through a wrapper such as mcp-remote.

ClientSupportedHow it sends the key
Cursor, VS Code, Windsurf, Claude Code, Codex CLIYesAuthorization header in the client configuration
Claude.ai and Claude Desktop custom connectorsYes, when the connector settings offer request headersRequest header on a connector added under your own account, never an organization connector
Claude Desktop local configurationYesmcp-remote wrapper
ChatGPT desktop app, Codex threadsYesHeader on the server entry under Plugins → MCPs
ChatGPT conversations and ChatGPT connectorsNoChatGPT connectors support only OAuth sign-in or no authentication

How clients ask for approval​

Every Appsmith MCP tool describes itself to the client with standard MCP tool annotations: whether it only reads, whether it can destroy data, and whether it reaches outside the Appsmith instance. Clients that decide on their own when to ask you for approval, such as Codex and the ChatGPT desktop app, use these annotations as follows by default; your own approval settings in the client can make it ask more often.

  • Read operations, such as listing workspaces or reading a page, run without a prompt. This includes running an action that Appsmith has verified as read-only against your datasource.
  • Non-destructive edits, such as building an app, adding a query, or hiding a page, run without a prompt. These changes are revision-checked and recorded, and they apply to the unpublished version of an existing app. build_application also deploys the first version of the new app it creates so that its viewer URL works; every later deploy goes through the prepare_publish and confirm_publish flow.
  • Destructive operations always use a two-step flow: a prepare_* tool that describes what is about to happen, followed by a confirm_* tool. The confirm step is the one the client asks you to approve. Deleting a page, query, API, or JS object; replacing the code of a JS object written in the editor; removing widgets from a page; deploying an app; rolling back a change; committing to Git; and running an action that can modify data all follow this flow. When replacing a JS object's code, the client cannot remove a function that the page still calls unless it explicitly acknowledges the broken calls. Replacing editor-written JS code requires MCP JS objects and MCP governance; if the client reports that these tools are unavailable, ask your Appsmith administrator to enable MCP JS objects and configure MCP governance.
  • Creating a Git branch and committing to Git push to your Git remote, so clients treat them as operations that reach outside Appsmith and ask for approval.

To remove widgets, the client calls prepare_remove_widgets and then confirm_remove_widgets. The prepare step lists every widget that will be removed, including everything inside a container, so you can review the full extent of the removal before you approve it. One removal can name up to 20 widgets, and each named widget is removed with everything inside it. patch_widgets does not remove widgets: it refuses a remove operation and directs the client to prepare_remove_widgets. Widgets on a page built from sections and zones can't be removed with prepare_remove_widgets and confirm_remove_widgets.

When the client supports MCP elicitation, Appsmith also shows its own approval prompt for the confirm step, with the exact scope of the change. Claude clients keep their own approval flow and do not change their behavior based on the annotations. The annotations describe the server's rules; they do not replace them.

What clients can build​

An MCP client can build a conditional form end to end, without follow-up work in the editor. Describe the form in plain language, for example: "Add a leave-request form where the end date can't be more than one year after the start date, and keep Submit disabled until the form is valid." The client turns the request into widget settings that Appsmith checks before it saves them.

Conditions​

A client can show, hide, require, or disable a widget based on other widgets on the page. A condition can check that a control, such as a select or radio group, has a given value, that a table has a selected row, that an input holds text, or a combination of values, such as "New contract is chosen and the start date is less than a year away."

  • Visible and Disabled conditions apply to any widget that has those properties.
  • Required conditions apply to form controls such as inputs, selects, radio groups, checkbox groups, and date pickers.
  • A custom Valid check applies to Input, Currency Input, and Phone Input widgets, for a rule that a named validation format can't express. See Valid in the Input reference.
  • A submit button can stay disabled until up to 10 form controls are valid.

Defaults and dates​

A widget's default value can come from another widget, from a field of a query's response, or from a calculation. This works for inputs, selects, multiselects, radio groups, checkboxes, switches, and date pickers. A Text widget's displayed value can be calculated the same way.

A date picker's default date, minimum date, and maximum date can depend on other widgets. For example, the end date can default to 14 days after today, and its maximum can be one year after the start date.

Date calculations can add days, months, or years, take the start of a day, count the days between two dates, and format a date as YYYY-MM-DD. They work as follows:

  • They use the viewer's local time zone. A YYYY-MM-DD value means midnight at the start of that day in the viewer's time zone, not in UTC.
  • Adding months or years keeps the day within the target month. 31 January plus one month is the last day of February, and 29 February plus one year is 28 February.
  • A date that doesn't exist, such as 30 February, gives no value instead of rolling over into the next month.

Current user​

A client can prefill a widget with the signed-in user's name, email, or username, for example the requester's email on a request form. These values come from the appsmith.user object, so each viewer sees their own details.

Tables, validation, and events​

  • Table columns: a client can add columns to an existing table or update them. A button or icon button column can open a modal or run an action for the row that was clicked, for example to open an edit form for that row.
  • Input validation: in addition to the existing formats, an input can accept letters only, letters and numbers only, or initials (2 to 4 letters). These formats accept only the letters A to Z, so a value with an accented letter, such as "José", is invalid. An input can also require a minimum or maximum length. An input uses either a named format or a length rule, not both.
  • Events: a client can run actions when the selection changes in a radio group or checkbox group, and when the selected options change in a multiselect.

Limits​

Appsmith refuses a change, and the client reports the reason, in these cases:

  • Raw code: a client can't write raw JavaScript or {{ }} text into a widget property. Every condition, default, and calculation is built from the operations described in this section.
  • JS object functions: a widget property can't call a function in a JS object. Functions that an MCP client writes run asynchronously, and widget properties can't wait for them. Ask the client to read a widget or query value instead, or to run the function from an event.
  • Curly braces in text: text inside a condition or calculation can't contain { or }.
  • Cycles: a property can't read itself, and two properties can't depend on each other. For example, a field's Required condition can't depend on whether that same field is valid. A cycle would stop the page from evaluating for every viewer.
  • Missing references: every widget and query that a condition, default, or calculation refers to must already exist. Ask the client to create the widget or query first.

Datasource environments​

A datasource that an MCP client creates is configured in the workspace's default datasource environment, usually Production. Queries that the client runs and datasource structures that it reads also use the default environment. To use the datasource in another environment, configure it for that environment in Appsmith. See Setup Datasource Environments.

Page visibility​

An MCP client can hide or show an existing page in an app's navigation with set_page_visibility. The change applies to the unpublished version of the app, so users see it after the next deploy. On a Git-connected app, it applies to the branch the client works on. The app's home page can't be hidden.

A hidden page is removed from navigation only. Users who can open the app can still reach the page by its URL or when another page navigates to it. To restrict who can open a page, use Granular Access Control.

An MCP client can make a widget event open another page of the same app with wire_event, or add a navigate step to a JS object function. Either way, the client can pass up to 10 URL query parameters to the page it opens. In an event, each value is a fixed value, a widget property, or a column of a table's selected row. In a JS object, each value is an expression, which can also read those values. For example, you can ask the client to "add a Details button that opens the Ticket Details page for the selected row of the tickets table".

The page that opens reads each value with appsmith.URL.queryParams.<key>, for example {{appsmith.URL.queryParams.id}}. See navigateTo and the queryParams property of the context object.

  • Navigation opens a page of this app in the same window. Opening a URL or a new window isn't supported.
  • Parameter names are plain identifiers: a letter or underscore, followed by letters, digits, or underscores.
  • In an event, a fixed text value can't contain single quotes, braces, backticks, or ${.
  • A page name that reads as an IP address or as localhost, such as 12 or 0x5db8d822, is refused when the client creates, renames, or navigates to a page. Add a letter to the page name.

Build workflows​

An MCP client can create and edit Appsmith Workflows and connect them to apps. These tools are available on Business Cloud and self-hosted Enterprise only, when your plan includes Workflows. Community Edition does not have them. If your plan does not include Workflows, every workflow tool returns "Workflows are not available on your Appsmith plan. Contact sales@appsmith.com to enable them."

ToolWhat it does
list_workflowsLists the workflows in a workspace, with each workflow's ID, name, and whether it has been deployed.
read_workflowReads a workflow's name, deploy state, logic, and queries. Logic written in the editor comes back as its source, and each query's SQL text, or REST method, path, query parameters, and body, comes back as written, including any secret typed into it. It never returns query headers or datasource configuration.
create_workflowCreates a workflow in a workspace, optionally with its logic.
rename_workflowRenames a workflow.
update_workflow_logicReplaces the workflow's logic, its Main JS object. The logic must define executeWorkflow(data), where data is the trigger data. Any code written in the editor is replaced.
create_workflow_queryAdds a SQL query to a workflow, on a datasource in the workflow's workspace.
create_workflow_rest_apiAdds a REST API call to a workflow, on a REST datasource in the workflow's workspace.
create_workflow_triggerAdds a query to an app page that starts a workflow when an app event runs it. See Start a workflow from an app.

An MCP client can't run, test, deploy, schedule, or delete a workflow, and it can't set up webhook triggers or approvals. A workflow built through MCP goes live only after someone deploys it in the Appsmith editor.

Start a workflow from an app​

create_workflow_trigger adds a Workflow query, with the Trigger workflow request type, to an app page. The client then wires the query to an event, such as a Button's onClick or a Table row action. This is the same query described in Trigger Workflow with Appsmith App.

  • Workflow. The client gets the workflow ID from list_workflows. The workflow must be in the app's workspace, and you must be able to run it.
  • Deploy first. The query runs the workflow's deployed version. Deploy the workflow in the editor before you use the trigger.
  • When it runs. The query never runs on page load. It runs only from the event it's wired to.
  • Payload. The payload is the trigger data that executeWorkflow receives, with at most 20 keys. Each value is either a fixed value or a widget value read when the query runs, such as Input1.text. Each widget must be on the page. A widget value that isn't set when the query runs is sent as null, so the workflow always receives every key.
  • Table row actions. To send a value from the row whose action ran, use the Table's triggeredRow, such as triggeredRow.id. Don't use selectedRow.
  • Creating it runs nothing. Creating the trigger doesn't start the workflow. If the client sends the same request again, it gets the existing query back instead of a duplicate.
Validate the trigger data

Anyone who can run the app can start the workflow and change the payload that the query sends. Write the workflow so that it checks every value it receives before it acts on it.

Manage MCP keys​

On the MCP keys page, you can review a key's name, status, creation date, and expiration date. You can also search for keys and filter them by status.

  • Rotate a key to replace its current secret. The old secret stops working immediately, and Appsmith displays the replacement only once. Update the client configuration with the new key.
  • Revoke a key to permanently prevent clients from using it.
  • Expired keys no longer authenticate. Create a new key or rotate the expired key, and update your client configuration.

Creating, rotating, and revoking MCP keys requires your normal signed-in Appsmith session. An MCP key itself cannot be used to manage keys.

If an administrator disables a user's Appsmith account, requests made with that user's MCP keys are rejected. Administrators should therefore apply the same least-privilege access practices to MCP users that they use elsewhere in Appsmith.

Troubleshoot a connection​

ProblemWhat to check
MCP keys is not visible under ProfileAsk an administrator to confirm that MCP Server is enabled, then refresh Appsmith.
The client cannot find the serverConfirm that the URL uses your Appsmith domain and ends in /mcp. On self-hosted Enterprise, confirm that the administrator clicked Save & Restart after enabling the server.
The client receives an authentication errorConfirm that the header is Authorization: Bearer YOUR_MCP_KEY and that the key has not expired, been rotated, or been revoked. Also confirm that MCP Server and your Appsmith user account are enabled. For a Codex CLI entry, confirm that the environment variable named in bearer_token_env_var is set; for a server added from the ChatGPT desktop app, confirm the header value on the entry under Plugins → MCPs.
The client connects but cannot perform an actionThe client has the permissions of the key owner. Confirm that your Appsmith user has access to the relevant organization, workspace, app, and action.
The client reports a revision_conflict errorThe page or JS object changed in Appsmith after the client read it, for example because someone edited it in the editor. Ask the client to read it again and retry the change.
A MongoDB query that the client created fails with "This query uses strict values, which need smart substitution", "…is not allowed for this query", or "…has a key that starts with $"Queries that the MCP client creates accept only plain JSON values in their bindings: strings, numbers, booleans, null, and plain objects or arrays, with no BSON values and no keys that start with $. They also need smart substitution. Turn on Smart BSON substitution in the query's settings, and make sure the bound values are plain JSON.
The configuration is rejected by the clientUse the tab for your client in Copy the key and connect your client. Common mismatches: VS Code expects servers and "type": "http"; Windsurf expects serverUrl; Claude Desktop needs mcp-remote.
Claude.ai reports that it cannot reach the serverThe connector was added with a sign-in option. Remove the connector and add it again with No sign-in and the authorization request header, as described in the Claude.ai tab.
ChatGPT reports that the Appsmith server is not exposed to the chat or that no tool was foundYou asked in a regular ChatGPT conversation. MCP servers added under Plugins → MCPs are available only in Codex threads. Start a new Codex thread on a local environment and ask there.
Codex or the ChatGPT desktop app asks for approval on every call, or reports that the server has no usable toolsThe instance is running an Appsmith version from before tool annotations were added, so the client treats every tool as destructive. Upgrade Appsmith.
After Appsmith was rolled back to an older version, the client can't edit a JS object that it wrote earlierA newer MCP server wrote the JS object in a format that the older version can't edit. The JS object still runs. Upgrade Appsmith to let the client edit it again.
On a multi-replica instance, requests fail with HTTP 404 on roughly every other callThe replicas are not sharing MCP sessions. Confirm that every replica runs a version that includes the shared session store and that APPSMITH_REDIS_URL points to one Redis instance that every replica uses. See Run MCP Server on more than one replica.
The client reports that a page name cannot read as an IP addressAdd a letter to the page name. See Page navigation with URL parameters.
Every authenticated request returns HTTP 503 with an MCP session relay errorA replica could not subscribe to its Redis channel at startup. Check Redis connectivity from that replica and confirm that the Redis user is allowed to SUBSCRIBE.
A workflow tool reports that Workflows are not available on your planYour plan doesn't include Workflows. Contact sales@appsmith.com to enable them.
create_workflow_trigger reports that the workflow is not in the application's workspaceAn app can start only a workflow in its own workspace. Move the workflow into the app's workspace, or create the workflow there.
create_workflow_trigger reports that you cannot run the workflowYour Appsmith user can't run the workflow. Ask a workspace administrator for permission to run it.
create_workflow_trigger reports that a widget is not on the pageA payload value names a widget that isn't on the page. Check the widget name, or add the widget to the page first.
create_workflow_trigger reports that the page already has a query with that nameAnother query on the page uses the name, or a trigger with that name points to a different workflow or payload. Choose another name.

Because MCP Server is in beta, please open a ticket in the Appsmith Support Portal for connection problems, unexpected behavior, or feature suggestions. Include your Appsmith version, deployment type, AI client name and version, and steps to reproduce the issue. Redact keys and other secrets from screenshots, logs, and configuration files. For more information, see Support at Appsmith.