MCP management

Use AI → MCP to configure tools that the AI assistant and built-in MCP server can call on behalf of a user.

Access to AI is controlled by the global view:ai-page permission. Separate global read: and edit: permissions control MCP server, tool, and collection configuration. For details, refer to the role model.

Overview

The AI assistant displays the following tool types:

• internal — Built-in portal tools described in the MCP server documentation.
• external — Tools retrieved from a connected upstream MCP server.
• custom — Custom MCP tools.

Tools of the external and custom types can be called only if they belong to an enabled MCP collection available to the user.

MCP servers

Connect an upstream MCP server to import its tools into the portal catalog.

1. Go to AI → MCP → MCP servers.
2. Select Connect.
3. On the Main information tab, specify Name, Identifier, Description, Owner, and Owning team.
4. On the Config tab:
   1. Enable the Enable toggle.
   2. Select a Transport: HTTP or SSE.
   3. Specify the upstream MCP server URL.
   4. If necessary, add Headers and Credentials for authentication.
5. Select Save.

After saving, open the server card and select Synchronize to load the tool catalog. On the Tools tab, enable the required tools and add Tags if necessary.

MCP tools

Create a custom MCP tool that the AI assistant calls directly without an upstream MCP server.

1. Go to AI → MCP → MCP tools.
2. Select Add.
3. On the Main information tab, specify Name, Description, Owner, Owning team, and Tags.
4. On the Config tab:
   1. Enable the Enable toggle.
   2. Define the Input schema as a JSON Schema with the root type object.
   3. If necessary, specify Path mapping as a JSON object that maps argument names to {placeholder} segments in the executor URL.
   4. If necessary, specify Query mapping as a JSON object that maps argument names to URL query parameter names.
   5. If necessary, specify Body mapping as a JSON object that maps argument names to JSON request body field names.
5. On the Authorization tab, specify the executor endpoint URL, HTTP method, Headers, and Credentials. The URL can contain {placeholder} segments for path parameters and credential placeholders such as {{ .credentials.tenant_id }}.
6. Select Save.

For example, assume the input schema defines the space_id argument, the executor URL is https://api.example.com/v1/spaces/{spaceId}/boards, and the path mapping is {"space_id": "spaceId"}. If the tool is called with space_id=42, the request is sent to https://api.example.com/v1/spaces/42/boards.

Arguments are passed to the executor endpoint as follows:

• Path mapping and query mapping apply to all HTTP methods. Only arguments listed in Query mapping are added to the URL as query parameters.
• For GET and DELETE, the request body is not sent. Arguments that are not listed in Path mapping or Query mapping are not passed.
• For POST, PUT, and PATCH, the JSON request body is built from Body mapping. If Body mapping is empty, the body contains all tool arguments, including the ones used in the path and query. If Body mapping is set, the body contains only the mapped arguments.

MCP collections

An MCP collection groups catalog tools and determines which tools are available to AI assistant users and external MCP clients.

1. Go to AI → MCP → MCP collections.
2. Select Create.
3. On the Main information tab, specify Name, Identifier, Description, Owner, and Owning team.
4. On the Config tab:
   1. Enable the Enable toggle.
   2. Under Tools, select tools from the available catalog. Each item includes the MCP server identifier in parentheses.
5. Select Save.

To let a user call collection tools, open the collection card menu and select Edit role bindings. Assign users or teams a role with the use:mcp-collections permission. For the permission list, refer to the role model.

The collection owner and super administrator automatically receive access to the collection.

Catalog

The Catalog section displays all tools available to the current user based on MCP collections and access permissions. This section is read-only. Edit tools on the MCP servers, MCP tools, and MCP collections pages.

Integration with the AI assistant and MCP server

Tools from MCP collections are used as follows:

• In the AI assistant, Available tools displays built-in tools and tools from available collections.
• The portal MCP server returns and calls the same collection tools available to the user based on their RBAC permissions.