> 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/how-to-connect-an-ai-client-to-frends-mcp.md).

# How to connect an AI client to Frends MCP

Allowing AI access to your Frends Tenant.

In order to let an AI client such as Claude or Copilot work on your Frends Tenant, you create a Platform Application, issue a token for it, and point the client at your Tenant's `/mcp` endpoint.

{% hint style="info" %}
Frends MCP is available from Frends version 6.3.2 onwards.
{% endhint %}

## Requirements <a href="#requirements" id="requirements"></a>

Frends MCP must be enabled on your Tenant. Not having it enabled disables the `/mcp` endpoint which is required to use Frends MCP. You can identify whether it is enabled by accessing the `/mcp` endpoint, if it gives status code `404 Page not found`, it is not enabled. Accessing it with browser should give status code `405 Method not allowed` if it is enabled. You need to be authenticated to the Frends Tenant in order to be able to check this.

You also need the `PersonalApplication.View` right. When Frends MCP is enabled, that right puts **API / MCP Applications** menu item in your user menu. If the entry is not there, it can mean the right is missing or that the feature is not enabled on the Tenant.&#x20;

You can only grant the token the scopes your own Frends permissions allow, so a token that covers Process deployment can only be issued by a user who holds the deployment right themselves.

You also need an AI client that supports remote MCP servers over HTTPS with a bearer token. Most current clients do, either directly or through a small connector configuration.

## Enabling Frends MCP

Configuring Frends MCP to be available for your Tenant is done on the server running the Frends UI.&#x20;

For standard deployment of Frends, you need to contact Frends Support to enable Frends MCP for your Tenant.&#x20;

For on-premise deployment of Frends, you can set the following settings in your Frends Control Panel configuration. These require UI service restart to apply.

First, you need to set `EnablePlatformMcp` flag to `true`.&#x20;

Secondly, you need to tell the UI service the Tenant's URL through `UiAddress` field. Unless this is set, the Frends MCP won't be enabled.

Finally, you need to set a value for `PlatformJwtAllowedIps` field. This restricts the MCP connections to only specific IP addresses or address spaces, providing security against unwanted usage of your Frends Tenant. Alternatively you need to explicitly allow connections from all IP addresses through this field, if that is wanted.

With these fields set, restarting the UI service will enable Frends MCP to be used through `/mcp` endpoint as well as configuring the applications and tokens in Frends Control Panel.

## How to create a Platform Application and a token <a href="#how-to-create-a-platform-application-and-a-token" id="how-to-create-a-platform-application-and-a-token"></a>

Open **API / MCP Applications** from your user menu in the Frends Control Panel, then create a new application. This is your own personal application: it belongs to you, and the Control Panel offers you only the scopes your own permissions allow. An administrator can instead create an application for the whole Tenant, which is managed centrally and can carry any scope.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2FqMry4TW21KRrvgks3c89%2Fscreenshot-rocks%20-%202026-08-27T092755.419.png?alt=media&amp;token=fd3cd5ff-b51b-42da-a436-01c9f5439535" alt=""><figcaption><p>Form for creating a new MCP application.</p></figcaption></figure>

Give the application a name that says which client will use it, for example "Claude Code, integration development", because the name is what you will look for later when you revoke it.

Select the scopes the application needs. Grant the smallest set that still lets the client do its job. A client that only explores and reports needs `process:view`, `process_instance:view`, `task:view` and `environment_variable:view`. A client that authors and deploys also needs `process:edit` and `process:deploy`. The full list is in [Frends MCP permissions](/reference/frends-mcp/frends-mcp-permissions.md).&#x20;

With the application saved, create a token for it. You choose an expiry date as you create it, from tomorrow up to two years out, so pick one that matches how long the client will be in use. The token is shown once, when it is created, so copy it straight into your client's configuration or a secret store. If you lose it, revoke it and create a new one.

{% hint style="warning" %}
The token is shown only once. Treat it like a password, and never paste it into a chat message, a ticket, or a source file.
{% endhint %}

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2Fe7QAGrvxexd1GjIijKgR%2Fimage.png?alt=media&amp;token=540761a4-ba85-4ddb-acd7-672136fb492e" alt=""><figcaption><p>Creating a token for the MCP application.</p></figcaption></figure>

## Configuring AI clients

Once you have your access token, you can proceed to configure your AI agents to use the Frends MCP server. The setup involves registering the Frends MCP endpoint within your preferred AI tools, allowing them to communicate securely with your Tenant.

You can also install the Frends Plugin for Claude and Codex to set up connection to the Frends MCP server, which additionally provides Skills for your AI to make  better use of the available Tools. The plugin is available from GitHub at [Frends Plugin for Claude and Codex CLI](https://github.com/Frends-Product-Management/frends-claude-plugin) as well as from the marketplaces.

### Claude Code (terminal)

For developers using the Claude Code terminal interface, adding the MCP server is most efficiently done through a direct command. You can use the terminal to register the new transport by executing the `claude mcp add` command with the appropriate parameters. This configuration requires specifying the transport type as `http` and providing the server URL, which for the standard Frends environment is `https://<your-tenant>.frendsapp.com/mcp`. You must include your access token in the authorization header by using the syntax `--header "Authorization: Bearer YOURTOKENHERE"`.

```
claude mcp add --transport http frendsmcp https://<your-tenant>.frendsapp.com/mcp --header "Authorization: Bearer YOURTOKENHERE"
```

After executing the command, you should verify the installation by opening `claude` and entering `/mcp` to ensure the new server is listed and active. If the server is disabled, you can toggle its status within the terminal interface to begin using the Frends integration features.

### Claude Desktop

If you prefer the Claude Desktop application, you will need to manually edit the configuration file to include the Frends MCP server details. You can locate this file by navigating to the application settings, selecting the developer tab, and clicking the button to edit the configuration. This action typically opens the `claude_desktop_config.json` file in your default text editor.

Inside the JSON file, you should locate the `mcpServers` property and add a new entry for Frends. This entry defines the command to run, such as `npx.cmd`, and includes the necessary arguments to point to the Frends MCP endpoint. The configuration should look like the following example, ensuring you replace the placeholder with your actual token.

```
"Frends": {
  "command": "npx.cmd",
  "args": [
    "-y",
    "mcp-remote@0.1.16",
    "https://<your-tenant>.frendsapp.com/mcp",
    "--transport",
    "http-only",
    "--header",
    "Authorization:Bearer YOURTOKENHERE"
  ]
}
```

After saving the changes to the configuration file, a full restart of the Claude Desktop application is required for the changes to take effect. In some environments, you may need to ensure all background processes for Claude are terminated through your operating system's task manager before restarting the application to guarantee the new settings are loaded correctly.

### GitHub Copilot (CLI)

The GitHub Copilot CLI relies on a specific configuration file located in your user profile directory. On Windows systems, this is found at `%USERPROFILE%\.copilot\mcp-config.json`, while Linux and macOS users will find it at `~/.copilot/mcp-config.json`. You will need to open this file and add the Frends MCP server details under the `mcpServers` property.

```
"Frends MCP": {
  "type": "http",
  "url": "https://<your-tenant>.frendsapp.com/mcp",
  "headers": {
    "Authorization": "Bearer YOURTOKENHERE"
  }
}
```

Once you have saved the file with your new server entry and token, you can start the `copilot` tool. The CLI will automatically detect the new MCP server, allowing you to ask questions about your Frends environment directly from your terminal session.

#### GitHub Copilot (VSCode extension) <a href="#github-copilot-vscode-extension" id="github-copilot-vscode-extension"></a>

For those who use GitHub Copilot within Visual Studio Code, the configuration can be accessed directly through the editor's Command Palette. You can open the palette by pressing `F1` or using the shortcut `Shift+Cmd+P` on macOS. Searching for and selecting the option to open the MCP user configuration will bring up a JSON file where you can define your server settings.You should add the Frends MCP server entry inside the `servers` property of this configuration file. After saving the file, a start button typically appears next to the new entry in the configuration view. Pressing this button initializes the connection, and you can then use the GitHub Copilot chat interface to interact with your Frends platform, enabling the AI to assist with your integration Tasks and system queries.

### How to check the connection works <a href="#how-to-check-the-connection-works" id="how-to-check-the-connection-works"></a>

Ask the client to list the available Tools. A working connection returns the Tools your scopes allow, and nothing else. If you granted only `process:view`, a short list is the correct result, not a sign of a problem.Then ask it something that needs a real call, for example how many Processes exist on the Tenant. A client that answers from the Tool list alone without calling anything will sound plausible and be wrong, so it is worth asking for a number that has to come from your data.

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

Most AI clients report a failure as "could not connect" and hide the status code, which is the one thing that tells you what went wrong. Test the endpoint and the token on their own first, so you have a code to look up:

```
curl -i -X POST "https://<your-tenant>.frendsapp.com/mcp" \ -H "Authorization: Bearer <your-token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

The status code on the first line is what the table below is keyed on. A `200` means the endpoint and the token are both fine and the problem is in the client's configuration.

<table data-search="false"><thead><tr><th>Symptom</th><th>Likely cause</th><th>What to do</th></tr></thead><tbody><tr><td><code>404 Not Found</code> on <code>/mcp</code></td><td>Frends MCP is not enabled on the Tenant.</td><td>Ask a Tenant administrator to enable Frends MCP feature</td></tr><tr><td><code>401 Unauthorized</code></td><td>The token is missing, expired, or revoked.</td><td>Check the header is really being sent, then check the token's expiry date and revocation state on the API / MCP Applications page</td></tr><tr><td>A connection that worked yesterday now returns <code>401</code>, and the token was neither expired nor revoked by hand</td><td>A change to your permissions, or to a role you hold, made a scope, Environment or tag on this application unavailable to you, so Frends revoked the application's tokens</td><td>Check what the application still carries, then create a new token for the permissions you still hold</td></tr><tr><td>Client connects but shows only the three orientation Tools (<code>get_overview</code>, <code>list_guides</code>, <code>get_guide</code>)</td><td>The token has no scopes, or none that match any other Tool. Those three need only a valid token</td><td>Add the scopes the client needs to the application, then issue a new token</td></tr><tr><td>Client connects but shows no Tools at all</td><td>Not a scope problem. A valid token always sees the three orientation Tools, so an empty list points at the client or the endpoint</td><td>Check the URL ends in <code>/mcp</code> and that the client is configured for a remote MCP server over HTTPS</td></tr><tr><td>A specific Tool is missing</td><td>Its required scope is not granted on the token</td><td>Look up the Tool in <a href="/reference/frends-mcp/frends-mcp-tools.md">Frends MCP Tools</a>, add the scope it names, and issue a new token. If the Portal will not let you select that scope on a personal application, your own rights no longer allow it, and the row above applies</td></tr><tr><td>Requests start failing under load</td><td>A rate limit configured for the Tenant's MCP endpoint has been reached</td><td>Slow the client down, or ask an administrator what the Tenant's MCP rate limit is</td></tr><tr><td>A <strong>deployed Process</strong> returns <code>401</code> to its own callers, and the AI client is working normally</td><td>Not an MCP problem. An HTTP Trigger defaults to <code>ApiPolicy</code> authentication, and no Tool creates API Policies</td><td>Configure an API Policy for that Process in the Portal. See the trigger section of <a data-mention href="/reference/frends-mcp/frends-mcp-tools.md">Frends MCP Tools</a></td></tr><tr><td>A deploy or a Process start fails, although the Tool is visible</td><td>The <code>deploymentId</code> is wrong, or the target Agent Group cannot take the version</td><td>Take the <code>deploymentId</code> from <code>list_processes</code> rather than constructing it, and check the target Agent Group in the Portal. If the Tool is not visible at all, this is a scope problem instead</td></tr></tbody></table>


---

# 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/how-to-connect-an-ai-client-to-frends-mcp.md?ask=<question>&goal=<user_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.