> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/frends-mcp/frends-mcp-permissions.md). # Frends MCP Permissions Allow AI to use only what it needs for your tasks. Frends MCP access is controlled through Platform Applications, tokens, and scopes. Together, they define which AI clients can connect to the Frends Tenant, which Platform MCP Tools they can see, and what actions they can perform. Frends MCP uses the same permission principles as the rest of Frends. An AI client does not receive open access to the Tenant simply because it can connect to the `/mcp` endpoint. It must authenticate with a valid token, and the token must be issued by a Platform Application that has the required scopes for the requested operation. {% hint style="info" %} Frends MCP is available from Frends version 6.3.2 onwards. {% endhint %} ## Frends MCP permission model Frends MCP serves its operations as MCP Tools. A client only sees the Tools that its token is allowed to use, so the result returned by `tools/list` is usually shorter than the full list of Frends MCP Tools available in Frends. Almost every Tool requires a scope, and scopes are the main way to control what an AI client can do in the Tenant. Some orientation Tools are available to every authenticated Frends MCP token. The `get_overview`, `list_guides`, and `get_guide` Tools require a valid token, but they do not require a specific scope. They allow a connected client to understand what the Frends MCP server is and read the available guides before using scoped Tools. A scope grants access to a defined capability, not to an entire feature area. For example, a token with `process:view` can list Processes but cannot execute or deploy a Process unless it also has the required scopes. This makes it possible to create read-only clients for exploration and troubleshooting, or more capable clients for development and deployment workflows. ## Platform Applications Frends MCP tokens are issued through Platform Applications. The application defines the identity and allowed scope set for the client, while the token is the credential the client uses when connecting to Platform MCP. This is why Platform Applications are the primary concept to configure before issuing a token. Tokens are created under an application, but the application determines what kind of access can be granted. If you need to change what an AI client can do, adjust the scopes of the application or create a token from another application with a different scope set. Name each application after the client or use case that will use it, such as `Claude Code, integration development` or `Support assistant, read-only`. The application name is important because Frends MCP activity is attributed to the application rather than to the token as a named person. A token that cannot be connected to a known client is difficult to audit and difficult to revoke safely. ### Personal applications A personal application is created from the user menu in Frends Control Panel. It belongs to the user who created it, and the available scopes are limited by that user’s own Portal rights. This means a user can only grant scopes that their own permissions allow. For example, a user who does not have deployment rights cannot create a personal application that grants an AI client permission to deploy Processes. Personal applications are useful when a user wants to connect an AI client for their own development, review, or investigation work. To create and manage personal applications, the user needs the `PersonalApplication.View` right. When Frends MCP is enabled and the user has this right, the API and MCP applications view is available from the user menu. ### Tenant-wide applications A Tenant-wide application is created and managed by an administrator. It is intended for centrally managed clients or shared use cases where access should not depend on a single user’s personal application. Tenant-wide applications can be configured with the scopes needed for the shared client, subject to administrative control. They are useful for organization-managed AI clients, service accounts, and long-running integrations where access must remain stable even if an individual user changes role or leaves the organization. Because Tenant-wide applications can be broader in scope, they should be named clearly and reviewed regularly. The name should make it obvious which client uses the application and why it exists. ### **Which kind of application to create** Use a **personal** application when one named person is responsible for the client, for example a developer connecting their own editor. Attribution is clear, and the token cannot outlive that person's rights. Use a **Tenant** application for a client that no single person owns, for example an automated pipeline. It survives changes to any individual's role, which is what you want for a shared client and exactly what you do not want for a personal one. Avoid creating a personal application for a shared client. Its settings are bound to the user's rights, so a change to the user's role can revoke that application's tokens and the shared client stops working for a reason that looks unrelated. ## Tokens A token is the credential that an AI client uses to authenticate to Frends MCP. The client sends the token as a bearer token in the `Authorization` header when connecting to the Tenant’s `/mcp` endpoint. The endpoint address is the Tenant address followed by `/mcp`, for example `https://.frendsapp.com/mcp`. Requests without a valid Platform Application token are rejected. **A token is shown only once when it is created**. Copy it immediately into the client configuration or a secure secret store. Avoid writing tokens directly into configuration files that may be committed to version control. Each token has an expiry date. When creating a token, choose an expiry that matches the expected lifetime of the client. Shorter-lived tokens are easier to manage for temporary testing or development use, while longer-lived tokens may be suitable for centrally managed clients when supported by clear ownership and revocation practices. Tokens can be revoked from the Platform Applications view. Revoke a token when the client using it is retired, when the token may have been exposed, or when the access is no longer appropriate. Revocation takes effect on the next request, which then fails with `401 Unauthorized`. Limiting user's permissions will also automatically revoke tokens for personal applications that depend on those permissions. ## Scopes Scopes define which Frends MCP Tools the client can use. They are configured on the Platform Application and apply to the tokens issued by that application. The Frends MCP server enforces scopes when the client connects and only exposes the Tools that the token is allowed to use. Scopes should be granted based on what the client actually needs to do. A client used only for exploration may need read scopes, while a client used for assisted development may also need permissions to create drafts, validate Processes, or deploy to a development Agent Group. Scopes do not always follow broad feature groupings. Always check the scope required by each Tool before granting access. Some Tools that may appear related can require different scopes, and some validation or orientation capabilities may require less access than expected.
ScopeGrants
process:viewRead the Process list, Process detail, drafts, and Process structure
process:editCreate and change Process drafts, and promote a draft into a Process version, which also deploys it to the development Agent Group
process:deployDeploy a Process version to an Agent Group
process:executeStart a Process
process_instance:viewRead Process Instance history and execution detail
environment_variable:viewRead Environment Variables
environment_variable:editCreate Environment Variables
task:viewRead the Task list and Task parameter schemas
task:editImport a Task package
### Choosing scopes Grant the smallest set that lets the client finish its job. Three combinations cover most real use. A **read-only** client that answers questions and reports on the Tenant needs `process:view`, `process_instance:view`, `task:view` and `environment_variable:view`. It can explain and diagnose, and it cannot change anything. An **authoring** client adds `process:edit`. It can create and validate drafts and save them as Process versions, and saving the draft also deploys the new version to the development Agent Group in the same call. This means that `process:edit` reaches the development Agent Group without a second decision. Note that you will also need `process:deploy` and `process:execute` scopes in order to run the Processes and deploy them to other Agent Groups, which the `process:edit` alone does not give access to. A **full development** client adds `process:deploy` and `process:execute`. Give this to a developer working in a development Environment, and think carefully before issuing it against Production. {% hint style="warning" %} `process:deploy` and `process:execute` can change what runs in an Environment. Treat them as you would treat deployment rights for a person. {% endhint %} ### What a user can grant Each scope requires a matching permission from the user in order to grant it. You cannot give a token more scope than your own role allows. For example, a user without deployment rights cannot issue a token that deploys.
ScopeActivity rule you must hold
process:view*.Process.View
process:edit*.Process.Edit
process:deploy*.Process.Deploy
process:execute*.Process.Start
process_instance:view*.ProcessInstance.View
environment_variable:view*.EnvironmentVariables.Edit
environment_variable:edit*.EnvironmentVariables.Edit
task:view*.Task.View
task:edit*.Task.Edit
The leading `*` is a wildcard for the activity's application area, not for an Environment. `*.Process.Deploy` means the `Process.Deploy` activity in any application area. Which Environments you may reach is evaluated separately, and these rules do not describe it. This check applies to a personal application, where the Portal offers you only the scopes your own rights allow. A Tenant administrator creating an application for the whole Tenant can select any of the nine. {% hint style="info" %} Both Environment Variable scopes map to the Environment Variables edit rule, because Frends has no view-only permission for Environment Variables. A user who can grant `environment_variable:view` therefore also holds edit rights themselves. The scope still limits the token to reading. {% endhint %} ## **Administrator actions** In **Administration > User Management**, the **MCP/API applications** tab manages Tenant applications, and the **User applications** tab lists personal applications across the Tenant. From there an administrator can inspect a personal application's tokens, revoke one, or delete the application. An administrator cannot create a token on someone else's behalf. User and role changes give a second, automatic safeguard: * A rights reduction revokes the tokens on each personal application the change affects. * Locking a user revokes all of that user's personal tokens. * Deleting a user revokes the tokens and detaches the applications. So there are two routes to revoking a departing person's access: revoke the tokens directly on the **User applications** tab, or disable the user and let the tokens go with them. For the per-Tool scope a client actually needs, see [Frends MCP Tools](/reference/frends-mcp/frends-mcp-tools.md), where every Tool names its own scope. ## Endpoint protection The `/mcp` endpoint requires an authenticated Platform Application token. Requests without one are rejected. Where a rate limit is configured for the Tenant's MCP traffic, a client making very frequent calls can be throttled. When Frends MCP is not enabled on the Tenant, the endpoint returns `404 Not Found` rather than an authentication error. ## Auditing Process changes made through Frends MCP land in the same places as changes made by a person in the Frends UI. A deployment appears in the Process version history, and an execution appears in the Process Instance log, which is where you look to see what a client actually did. Because a token is not a person, the application name is what identifies the caller. One application per client keeps that attribution usable. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.frends.com/reference/frends-mcp/frends-mcp-permissions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.