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.

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 or adding a query, 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; deploying an app; rolling back a change; committing to Git; and running an action that can modify data all follow this flow.
  • 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.

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.

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 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.
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.
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.

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.