MCP Servers
An MCP server exposes a flow as a Model Context Protocol server that external clients — such as Claude Desktop or Cursor — can connect to and call. Each non-private action in the flow becomes an MCP tool. When a tool is called, the action runs in the solution as the connected user, with that user's roles and permissions.
A flow is exposed as an MCP server by selecting MCP as the flow type when creating the flow. An MCP flow is dedicated to this purpose: its actions are MCP tools, and cannot also be exposed as API Endpoints or run on Schedules.
Important
For an MCP server to be reachable in a given environment, the Enable Flow Service checkbox must be selected in the Environment Configuration.
External clients connect on behalf of an individual user using OAuth. The Allow external client access checkbox in the Environment Configuration for the environment must also be selected. See External clients below.
Usage
To create an MCP flow:
Click Create Flow.
Select MCP.
Set the API root path. This becomes part of the server URL.
To add an MCP tool to an existing MCP flow:
Open the flow.
Click + Create MCP Tool in the MCP Tools panel.
Enter a name for the tool.
The MCP server URL for a flow is:
https://SOLUTION-HOSTNAME/api/mcp/API-ROOT-PATH.
For example, if the API root path is sales, the URL would be:
https://your-solution.appfarm.app/api/mcp/sales.
Configure your MCP client (for example, Claude Desktop or Cursor) with this URL. The client discovers Appfarm as the identity provider, and the user is prompted to sign in and approve the connection. See External clients for the connection flow, and Connected apps for where the user manages approved connections.
To view and test the tools on an MCP server, open the MCP Inspector.
Server properties
The flow's own properties determine what the MCP server advertises to clients.
Name
Used as the server name advertised to clients. Must follow the naming rules below.
Description
Used as the server instructions — guidance an agent reads to understand what the server is for and when to use its tools.
API Root Path
The path segment used in the server URL. Must consist of valid URL characters, in kebab-case (for example, customer-lookup).
MCP tools
Each non-private action in an MCP flow is exposed as one MCP tool. The action's name, description, action params, and returnable action variables and action data sources determine how the tool is advertised and how its responses are shaped.
An action marked Private is not exposed as a tool. Private actions are still callable from other actions in the same flow using the Run Action action node, which is useful for shared helper logic that should not be reachable from outside the flow.
Tool properties
Name
Used as the tool name advertised to clients. Must follow the naming rules below.
Description
Used as the tool description. An agent reads this to decide whether and how to call the tool. The descriptions of action variables marked Return from action are appended automatically as a list of return values.
Private
When selected, the action is excluded from the MCP server. The action remains callable from other actions in the flow via Run Action.
Tool input
The action's action params define the tool's input schema. Each action param becomes one field on the tool input. The action param's Data Type determines the type advertised to the client.
Boolean
boolean
Integer
integer
Float
number
Multi Enum, Multi Reference
array of strings
Schema
object, with fields built recursively from the schema's properties
All other types (String, Enum, Reference, Date, Date Time)
string
The action param's Description is exposed verbatim to the client. An action param is required on the tool input only if it is marked Required on the action param.
Good to know
Enum and reference params are advertised as plain strings. The accepted values are not enumerated in the tool schema.
Action param names must be unique within an action. If two params resolve to the same name, only the first is exposed; the rest are dropped.
Tool output
When a tool is called, the action runs and returns:
All action variables marked Return from action.
All action data sources marked Return from action.
These are serialized into a single JSON payload and returned to the client. If the action throws an exception, the error is returned to the client and the call is marked as failed.
Good to know
The response is a JSON-encoded string in an MCP text content block. Clients receive the JSON as text and parse it themselves; structured MCP output is not used.
Naming rules
MCP clients identify servers and tools by name, and agents read those names to choose which tool to call. The platform enforces the MCP naming rules on flow names and tool names.
Flow name
snake_case ASCII, matching [a-zA-Z0-9_.-], 1–128 characters.
MCP Tool name
snake_case ASCII, matching [a-zA-Z0-9_.-], 1–128 characters.
API Root Path
kebab-case URL characters (for example, customer-lookup).
Convert non-ASCII characters to ASCII equivalents. For Norwegian names, that means æ → ae, ø → oe, å → aa.
Best practice
Names and descriptions are how an agent decides which tool to call. Write them so a reader who knows nothing about the flow can tell what each tool does and when to use it. Vague names like do_thing are unlikely to be selected even when they are the right tool.
External clients
An external client is a third-party application — such as Claude Desktop or Cursor — that one of your users connects to an MCP server as themselves, using their Appfarm account. The user signs in at accounts.appfarm.io, approves a consent screen, and the client receives a token that lets it call the MCP server on the user's behalf. Tool calls then run as that user, with that user's roles and permissions in the solution.
This is separate from the service account and API key model used by API Endpoints. The two models coexist; enabling external clients does not change anything about existing service accounts or API keys, which continue to work as before.
Enabling external clients
External clients are off by default. To allow external clients to connect to MCP servers in an environment, select the Allow external client access checkbox in the Environment Configuration for that environment.
While Allow external client access is cleared:
External MCP clients cannot discover the solution.
External bearer tokens presented to an MCP server are rejected.
The Appfarm sign-in flow rejects authorization requests targeting the solution.
Clearing this checkbox is a hard kill-switch. New connections cannot be made and existing connections cannot be refreshed. Access tokens that have already been issued continue to work until they expire — see Revoking access.
The consent screen
After signing in, the user sees a consent screen before any external client can connect. The consent screen names:
The app requesting access.
The solution and environment being connected to.
The full resource URL the app will call.
What the app will be able to do — act on the user's behalf in the solution, read basic profile information, and stay signed in.
That the user can revoke access at any time from Connected apps.
The consent screen displays differently depending on whether the app is verified by Appfarm.
Verified app. The app's name and logo anchor the screen, with a Verified by Appfarm affirmation. An app becomes verified through review by Appfarm staff, or because its sign-in redirect targets a domain Appfarm trusts (for example,
claude.ai).Unverified app. The screen leads with the destination the sign-in is delivered to — the redirect host, such as
claude.ai— rather than the name the app has chosen for itself. The self-claimed name is shown on a secondary line.
Good to know
A malicious app can choose any name it likes for itself, but it cannot fake the destination its sign-in is delivered to. Leading with the destination on unverified apps is what protects users from an app impersonating a familiar brand.
Tokens and permissions
When the user approves the consent screen, the client receives an access token that is:
Bound to one solution. A token approved for one solution cannot be used against another, even if both are protected by the same Appfarm login.
Scoped to the approving user's permissions. The client can do exactly what the user can do in the solution — no more. It cannot expand its access without the user approving a new consent screen.
Short-lived. External client access tokens last 15 minutes. The client refreshes them silently as long as the connection remains approved.
Revoking access
There are four ways to end an external client's access, from per-user to fleet-wide.
The user revokes one app. Done from Connected apps.
The connection and stored tokens are deleted immediately. The client can no longer refresh, and its current access token stops working within 15 minutes.
The user invalidates all sessions. Done from the security panel of the user's Appfarm account.
All of the user's sessions, including external client tokens, are invalidated immediately. Use this for lost-device or suspected-compromise situations.
An administrator clears Allow external client access. Done per environment in the Environment Configuration.
All external client connections to the solution stop refreshing immediately. Existing access tokens stop working within 15 minutes.
Appfarm disables an app fleet-wide.
Appfarm can disable an individual app so it cannot be used on any solution.
Important
Revocation takes up to 15 minutes to take full effect. External client access tokens are validated locally by the platform without a callback to Appfarm, so a token already issued cannot be cancelled mid-life — it stops being valid when it expires.
For an instantaneous cutoff (for example, in a security incident), the user should invalidate all sessions in addition to revoking the connection.
Limitations
One flow type per flow. An action in an MCP flow cannot also be exposed as an API Endpoint or run on a Schedule. Share helper logic between flows by extracting it into another flow and calling it with Run Flow.
Output is JSON inside a text block. Structured MCP output is not produced; the client must parse the JSON itself.
No streaming, no sessions. The server uses streamable HTTP with stateless JSON responses. Each tool call is a single request/response.
Enums and references are advertised as strings. The accepted values are not listed in the tool schema.
Last updated
Was this helpful?