---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/using-mcp-in-ca.md
  - https://sourcecraft.dev/portal/docs/ru/code-assistant/operations/agent/mcp/using-mcp-in-ca.md
title: Using MCP in SourceCraft Code Assistant
description: Complete guide to configuring, enabling, and managing MCP servers in SourceCraft Code Assistant.
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt


# Using MCP in SourceCraft Code Assistant

<!-- source: en/_includes/code-assistant/only-in-vscode.md -->
{% note warning %}

This feature is only available in Visual Studio Code.

{% endnote %}
<!-- endsource: en/_includes/code-assistant/only-in-vscode.md -->

The MCP (Model Context Protocol) server acts as a bridge, providing Code Assistant with access to a wider range of tools and external services, such as databases, APIs, or custom scripts. It uses a standard communication method, allowing Code Assistant to use these external capabilities.

For more information, see [What is MCP](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/what-is-mcp.md).

<!-- source: en/_includes/code-assistant/recommended-mcp-servers.md -->
{% note info %}

You can view the list of Yandex Cloud and SourceCraft MCP servers, as well as recommended MCP servers, in [MCP servers](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/recommended-mcp-servers.md#servers).

{% endnote %}
<!-- endsource: en/_includes/code-assistant/recommended-mcp-servers.md -->

## Configuring MCP servers {#configuring-mcp-servers}

You can manage MCP server configurations at the following levels:
* Global configuration: Stored in the `mcp_settings.json` file, accessible through the VS Code settings. These settings apply to all your workspaces unless redefined by a project-level configuration.
* Project-level configuration: Defined in the `.codeassistant/mcp.json` file in the root folder of your project. This allows you to set up project-specific servers and share configurations with your team by adding the file to your version control system. Code Assistant automatically detects and uploads this file if it exists.

{% note warning %}

If the repository is hosted on SourceCraft, the MCP is pre-installed to interact with it. This MCP allows you to create [pull requests](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#pr) on the platform, read and perform [tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#issues), and much more. The system prompt also includes tips on MCP usage and the repository slug.

{% endnote %}

If a server name exists in both the global and project configurations, the project-level configuration takes precedence.

### Editing MCP settings files {#editing-mcp-settings-files}

You can edit both global and project-specific MCP configuration files directly from the MCP settings menu in Code Assistant:

1. Click <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M3 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3M9.5 8a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0m5 0a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0" clip-rule="evenodd"/></svg> in the chat's top panel and select MCP servers.
1. Select the appropriate option:
    * <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M11.423 1A3.577 3.577 0 0 1 15 4.577c0 .27-.108.53-.3.722l-.528.529-1.971 1.971-5.059 5.059a3 3 0 0 1-1.533.82l-2.638.528a1 1 0 0 1-1.177-1.177l.528-2.638a3 3 0 0 1 .82-1.533l5.059-5.059 2.5-2.5c.191-.191.451-.299.722-.299m-2.31 4.009-4.91 4.91a1.5 1.5 0 0 0-.41.766l-.38 1.903 1.902-.38a1.5 1.5 0 0 0 .767-.41l4.91-4.91a2.08 2.08 0 0 0-1.88-1.88m3.098.658a3.6 3.6 0 0 0-1.878-1.879l1.28-1.28c.995.09 1.788.884 1.878 1.88z" clip-rule="evenodd"/></svg> **Edit Global MCP**: Opens the global file named `mcp_settings.json`.
    * <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M11.423 1A3.577 3.577 0 0 1 15 4.577c0 .27-.108.53-.3.722l-.528.529-1.971 1.971-5.059 5.059a3 3 0 0 1-1.533.82l-2.638.528a1 1 0 0 1-1.177-1.177l.528-2.638a3 3 0 0 1 .82-1.533l5.059-5.059 2.5-2.5c.191-.191.451-.299.722-.299m-2.31 4.009-4.91 4.91a1.5 1.5 0 0 0-.41.766l-.38 1.903 1.902-.38a1.5 1.5 0 0 0 .767-.41l4.91-4.91a2.08 2.08 0 0 0-1.88-1.88m3.098.658a3.6 3.6 0 0 0-1.878-1.879l1.28-1.28c.995.09 1.788.884 1.878 1.88z" clip-rule="evenodd"/></svg> **Edit Project MCP**: Opens the project file named `.codeassistant/mcp.json`. If there is no such file, Code Assistant will create it automatically.

    Both files use JSON format with an `mcpServers` object containing named server configurations:

    ```json
    {
      "mcpServers": {
        "server1": {
          "command": "python",
          "args": ["/path/to/server.py"],
          "env": {
            "API_KEY": "your_api_key"
          },
          "alwaysAllow": ["tool1", "tool2"],
          "disabled": false
        }
      }
    }
    ```

### Transport types {#transport-types}

MCP supports the following transport types for communication with servers: STDIO for local servers, Streamable HTTP (recommended for new remote servers), and SSE (for legacy remote servers).

#### STDIO transport {#stdio-transport}

Used for local servers running on your computer:
* Data exchange via standard input/output streams.
* Low latency (no network overhead).
* Increased security (no network availability).
* Simplified setup (no HTTP server required).
* Runs as a child process on your computer.

For more information, see [STDIO transport](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/server-transports.md#stdio).

STDIO configuration example:

```json
{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/path/to/project/root", // Optional: Specifying a working directory
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}
```

Where:
* `command`: Executable file to run, e.g., `node`, `python`, `npx`, or an absolute path. This is a required setting.
* `args`: Array of string arguments provided to your command. This is an optional setting. You can use system environment variables using the `${env:VARIABLE_NAME}` syntax.
* `cwd`: Working directory from which the server process will be launched. This is an optional setting. If not specified, the system will use the path of the workspace's first folder or the working directory of the main process. This setting is useful if the server script depends on relative paths.
* `env`: Object containing environment variables to set during the server process. This is an optional setting.
* `alwaysAllow`: Optionally, array of tool names from this server that will be auto-approved.
* `disabled`: Set to `true` to disable this server configuration. This is an optional setting.

#### Using system environment variables in arguments {#environment-variables}

You can reference system environment variables in the `args` array using the `${env:VARIABLE_NAME}` syntax. This allows you to provide sensitive information, such as API keys or tokens, from the system environment without explicitly mentioning them in the configuration:

```json
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_PERSONAL_ACCESS_TOKEN}",
        "ghcr.io/github/github-mcp-server"
      ],
      "alwaysAllow": [
        "get_pull_request"
      ]
    }
  }
}
```

In this example, `${env:GITHUB_PERSONAL_ACCESS_TOKEN}` will be replaced with the value of the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable from your system. This is especially useful when:
* You are working with Docker containers that you need to provide with environment variables.
* You want to exclude sensitive data from configuration files.
* You use the same configuration in different environments with different credentials.

{% note info %}

Your environment variable must exist on your system for this to work. You can set system environment variables through operating system settings or shell configuration files, e.g., `.bashrc`, `.zshrc`, or Windows environment variables.

{% endnote %}

#### Streamable HTTP transport {#streamable-http-transport}

It is a modern standard for remote servers accessible over HTTP/HTTPS, providing greater flexibility and replacing the legacy SSE transport for new implementations:
* Data exchange over HTTP POST/GET with a single MCP endpoint.
* Optionally uses Server-Sent Events (SSE) for streaming.
* Can be hosted on a remote server.
* Supports multiple client connections.
* Requires network access.
* Supports centralized deployment and management.

For more information, see [Streamable HTTP transport](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/server-transports.md#streamable-http).

Streamable HTTP configuration example:

```json
{
  "mcpServers": {
    "modern-remote-server": {
      "type": "streamable-http",
      "url": "https://your-modern-server.com/api/mcp-endpoint",
      "headers": {
        "X-API-Key": "your-secure-api-key"
      },
      "alwaysAllow": ["newToolA", "newToolB"],
      "disabled": false
    }
  }
}
```

Where:
* `type`: Must be set to `"streamable-http"`. This is a required setting.
* `url`: Full URL of a single endpoint of the remote MCP server, e.g., `https://your-server.com/mcp`. This is a required setting.
* `headers`: Object containing custom HTTP headers to send with requests, such as for authentication tokens. This is an optional setting.
* `alwaysAllow`: Optionally, array of tool names from this server that will be auto-approved.
* `disabled`: Set to `true` to disable this server configuration. This is an optional setting.

#### SSE Transport (legacy) {#sse-transport-legacy}

Used for legacy remote servers accessible over HTTP/HTTPS:
* Data exchange over the Server-Sent Events protocol (usually requires separate endpoints for client-server and server-client communication).
* Can be hosted on a remote server.
* Supports multiple client connections.
* Requires network access.
* Supports centralized deployment and management.

For new remote server implementations, we recommend to use [Streamable HTTP](#streamable-http-transport).

For more information, see [SSE Transport (legacy)](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/server-transports.md#sse-transport).

SSE configuration example (legacy):

```json
{
  "mcpServers": {
    "legacy-remote-server": {
      "type": "sse", // Explicitly specify as SSE
      "url": "https://your-legacy-server-url.com/mcp-base", // Base URL
      "headers": {
        "Authorization": "Bearer your-legacy-token"
      },
      "alwaysAllow": ["oldToolX"],
      "disabled": false
    }
  }
}
```

Where:
* `type`: Should be set to `"sse"` if a `url` is specified for an SSE server to distinguish from Streamable HTTP. This setting is optional but recommended for clarity. If a `url` is specified but there is no `type`, Code Assistant may attempt to determine the type automatically, but explicit specification is preferred.
* `url`: Base URL of the remote MCP server. This is a required setting. For legacy SSE, this typically means separate paths such as `/events` (for the SSE stream) and `/message` (for POST requests) that will be determined or expected by the server.
* `headers`: Object containing custom HTTP headers to send with requests, such as for authentication tokens. This is an optional setting.
* `alwaysAllow`: Optionally, array of tool names from this server that will be auto-approved.
* `disabled`: Set to `true` to disable this server configuration. This is an optional setting.

## Enabling or disabling MCP servers {#disable-mcp-servers}

Disabling MCP servers removes all MCP-related logic and definitions from the system request, reducing token usage. This will prevent Code Assistant from connecting to any MCP servers and make the `use_mcp_tool` and `access_mcp_resource` tools unavailable. Configure this setting if you do not plan to use MCP servers. This parameter is enabled by default.

1. Click <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M3 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3M9.5 8a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0m5 0a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0" clip-rule="evenodd"/></svg> in the chat's top panel and select MCP servers.
1. Enable or disable the **Enable MCP Servers** option.

## Enabling or disabling MCP server creation {#enabling-or-disabling-mcp-server-creation}

Disabling MCP server creation removes the instructions from the system request that Code Assistant uses to write MCP servers, but does not remove the context associated with their operation. This reduces token usage. This parameter is enabled by default.

1. Click <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M3 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3M9.5 8a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0m5 0a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0" clip-rule="evenodd"/></svg> in the chat's top panel and select MCP servers.
1. Enable or disable the **Enable MCP Server Creation** option.

## How to use Code Assistant to create an MCP server {#how-to-use-ca-to-create-mcp-server}

If you need a specific tool or feature that is not available through existing MCP servers, you can ask Code Assistant to create a new one.

{% note tip %}

Make sure the **Enable MCP Server Creation** option is enabled in the MCP settings panel. If this option is disabled, Code Assistant will not have the necessary instructions to create a server.

{% endnote %}

1. Formulate a request: explicitly ask Code Assistant for a new tool or feature. Here is an example:
    * `Create an MCP tool that fetches the current price of Bitcoin.`
    * `I need a tool that connects to my company's internal user database via its API.`
    * `Create an MCP server to interact with the GitHub Gist API.`
1. After your request, Code Assistant will perform the following steps:
    * Receive internal instructions to create the server.
    * Create a basic server project (usually in TypeScript) in the default MCP directory unless you specify otherwise.
    * Write the code to implement the requested tool, which includes handling the necessary API calls.
    * If the tool requires API keys or other credentials, Code Assistant will prompt you for them using the `ask_followup_question` tool to securely configure them as environment variables for the server.
    * Automatically add the new server configuration to your global `mcp_settings.json` file or `.codeassistant/mcp.json` project file.
    * Attempt to connect to the newly configured server to make its tools available.
1. If the previous steps were successful, Code Assistant will confirm the creation, and the new server and its tools will appear in your list of MCP servers, ready for use.

This feature allows you to customize Code Assistant capabilities by creating required integrations directly from your requests.

## Managing individual MCP servers {#managing-individual-mcp-servers}

Each MCP server has its own configuration panel where you can edit settings, manage tools, and monitor its operation. To access these settings:

1. Click <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M3 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3M9.5 8a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0m5 0a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0" clip-rule="evenodd"/></svg> in the chat's top panel and select MCP servers.
1. In the list of MCP servers, find the one you need and perform one of the following actions.

### Deleting a {#deleting-a-server} server

1. Click <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M9 2H7a.5.5 0 0 0-.5.5V3h3v-.5A.5.5 0 0 0 9 2m2 1v-.5a2 2 0 0 0-2-2H7a2 2 0 0 0-2 2V3H2.251a.75.75 0 0 0 0 1.5h.312l.317 7.625A3 3 0 0 0 5.878 15h4.245a3 3 0 0 0 2.997-2.875l.318-7.625h.312a.75.75 0 0 0 0-1.5zm.936 1.5H4.064l.315 7.562A1.5 1.5 0 0 0 5.878 13.5h4.245a1.5 1.5 0 0 0 1.498-1.438zm-6.186 2v5a.75.75 0 0 0 1.5 0v-5a.75.75 0 0 0-1.5 0m3.75-.75a.75.75 0 0 1 .75.75v5a.75.75 0 0 1-1.5 0v-5a.75.75 0 0 1 .75-.75" clip-rule="evenodd"/></svg> next to the MCP server you want to delete.
1. In the confirmation window, click **Delete**.

### Restarting a {#restarting-a-server} server

Click <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5a6.5 6.5 0 1 0 6.445 7.348.75.75 0 1 0-1.487-.194A5.001 5.001 0 1 1 11.57 4.5h-1.32a.75.75 0 0 0 0 1.5h3a.75.75 0 0 0 .75-.75v-3a.75.75 0 0 0-1.5 0v1.06A6.48 6.48 0 0 0 8 1.5" clip-rule="evenodd"/></svg> next to the MCP server you want to restart.

### Enabling or disabling a server {#enabling-or-disabling-a-server}

Click the toggle <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M0 8a5.5 5.5 0 0 1 5.5-5.5h5a5.5 5.5 0 1 1 0 11h-5A5.5 5.5 0 0 1 0 8m6.5 0a4 4 0 1 0 8 0 4 4 0 0 0-8 0" clip-rule="evenodd"/></svg> next to the MCP server you want to turn on or off.

### Network timeout {#network-timeout}

To set the maximum time to wait for a response after invoking a tool on an MCP server:
1. Expand the drop-down list <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M5.47 13.03a.75.75 0 0 1 0-1.06L9.44 8 5.47 4.03a.75.75 0 0 1 1.06-1.06l4.5 4.5a.75.75 0 0 1 0 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0" clip-rule="evenodd"/></svg> next to the MCP server.
1. Set the time in the **Network Timeout** field. The default value is 60 seconds, but you can set a value between 30 and 300 seconds.

### Tool auto-approval {#auto-approving-mcp-tools}

[Auto-approval](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/auto-approving-actions.md) of MCP tools works for each tool individually and is disabled by default. To set up auto-approval:
1. On the <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><g fill="currentColor"><path d="M9.97 4.47a.75.75 0 1 1 1.06 1.06L7.665 8.895l1.363 1.515 4.942-4.94a.75.75 0 1 1 1.06 1.06l-5.5 5.5a.75.75 0 0 1-1.088-.028l-1.84-2.045L5.53 11.03a.75.75 0 0 1-1.094-.036l-3.5-4a.75.75 0 0 1 1.128-.988l2.972 3.396.56-.561-1.654-1.839a.75.75 0 0 1 1.116-1.004l1.601 1.78z"/><path d="M9.97 4.47a.75.75 0 1 1 1.06 1.06L7.665 8.895l1.363 1.515 4.942-4.94a.75.75 0 1 1 1.06 1.06l-5.5 5.5a.75.75 0 0 1-1.088-.028l-1.84-2.045L5.53 11.03a.75.75 0 0 1-1.094-.036l-3.5-4a.75.75 0 0 1 1.129-.988l2.971 3.396.56-.561-1.654-1.839a.75.75 0 0 1 1.116-1.004l1.601 1.78z"/></g></svg> **Auto-approve** panel, enable <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M0 8a5.5 5.5 0 0 1 5.5-5.5h5a5.5 5.5 0 1 1 0 11h-5A5.5 5.5 0 0 1 0 8m6.5 0a4 4 0 1 0 8 0 4 4 0 0 0-8 0" clip-rule="evenodd"/></svg> MCP.
1. Expand the required MCP server and select the **Auto-Run** option for specific tools.

Once enabled, Code Assistant will automatically approve the use of this tool without asking. 

{% note info %}

The global **MCP** setting in the <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><g fill="currentColor"><path d="M9.97 4.47a.75.75 0 1 1 1.06 1.06L7.665 8.895l1.363 1.515 4.942-4.94a.75.75 0 1 1 1.06 1.06l-5.5 5.5a.75.75 0 0 1-1.088-.028l-1.84-2.045L5.53 11.03a.75.75 0 0 1-1.094-.036l-3.5-4a.75.75 0 0 1 1.128-.988l2.972 3.396.56-.561-1.654-1.839a.75.75 0 0 1 1.116-1.004l1.601 1.78z"/><path d="M9.97 4.47a.75.75 0 1 1 1.06 1.06L7.665 8.895l1.363 1.515 4.942-4.94a.75.75 0 1 1 1.06 1.06l-5.5 5.5a.75.75 0 0 1-1.088-.028l-1.84-2.045L5.53 11.03a.75.75 0 0 1-1.094-.036l-3.5-4a.75.75 0 0 1 1.129-.988l2.971 3.396.56-.561-1.654-1.839a.75.75 0 0 1 1.116-1.004l1.601 1.78z"/></g></svg> **Auto-approve** panel takes precedence: if it is disabled, no MCP tools will be automatically approved.

{% endnote %}

## Finding and installing MCP servers {#finding-and-installing-mcp-servers}

You can find and install MCP servers in Code Assistant on your own. To do this:
* Check the lists of community-supported MCP servers on GitHub.
* Ask Code Assistant to help you find or even create MCP servers if the [Enable MCP Server Creation](#enabling-or-disabling-mcp-server-creation) option is enabled.
* Create custom MCP servers using the SDK to extend the capabilities of Code Assistant with your own tools. For complete SDK documentation, see the [MCP repository on GitHub](https://github.com/modelcontextprotocol/).

<!-- source: en/_includes/code-assistant/recommended-mcp-servers.md -->
{% note info %}

You can view the list of Yandex Cloud and SourceCraft MCP servers, as well as recommended MCP servers, in [MCP servers](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/recommended-mcp-servers.md#servers).

{% endnote %}
<!-- endsource: en/_includes/code-assistant/recommended-mcp-servers.md -->

## Using MCP tools in your workflow {#using-mcp-tools-in-your-workflow}

Once you set up the MCP server, Code Assistant will automatically detect available tools and resources. Using these tools effectively requires understanding the basic steps of interaction and how Code Assistant interprets the tools you provide.

### Main workflow steps {#main-workflow-steps}

Your interaction with MCP tools will typically follow this sequence:

#### 1. Starting a task {#starting-a-task}

Start by entering your request in the Code Assistant chat interface.

#### 2. Identifying a Code Assistant tool {#identifying-mcp-tools}

Code Assistant analyzes your request to determine if an available MCP tool can help. This step is highly dependent on the quality of your MCP tool descriptions.

##### Critical role of descriptions {#critical-role-of-descriptions}

Tool descriptions significantly impact the Code Assistant's ability to:
* Determine the tool fitting the task.
* Understand how to structure the required parameters.
* Understand how to avoid misinterpretation of the tool's capabilities.

In this light, clear, concise, and informative descriptions of both the tools and their parameters are crucial. Unclear or missing information, especially regarding parameters, may make it very difficult to select or use a Code Assistant tool.

For example, if you type `Analyze the performance of my API` in your request, it might result in Code Assistant selecting the MCP tool designed for testing API endpoints. Successful identification and use of this Code Assistant tool directly depends on the quality of its description.

##### Recommendations for identifying MCP tools {#best-practices-for-identifying-mcp-tools}

To ensure Code Assistant can effectively use your MCP tools, consider the following when defining them on the server:
* Tool name: select a descriptive and unambiguous name that clearly indicates the tool's primary function.
* Tool description: provide a detailed summary of what the tool does, its purpose, and any important context cues or prerequisites for its use. Explain the result or outcome of using the tool.
* Describing parameters is critical. For each parameter:
  * Clearly state its purpose and the type of data expected, such as `User ID to search`, `Path to file to process`, `Search query string`.
  * Provide any format requirements, limitations, or an example of an acceptable value, if applicable.
  * Specify whether the parameter is optional or required. Although this is usually handled by the MCP schema, a note might be useful.
* Clarity for AI: write descriptions as if you were explaining the tool to another developer or AI. The more context Code Assistant has, the better it can integrate the tool into its workflows. If the tool is designed for use in a specific sequence or in combination with other tools, mentioning that may also be helpful.
* Adding user instructions: in addition to descriptions built into the MCP server, you can additionally direct Code Assistant to use specific MCP tools by providing [user instructions](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/chat-rules.md). This allows you to define preferred approaches, describe complex workflows involving multiple tools, or indicate when a particular MCP tool should be prioritized or avoided.

#### 3. Calling a tool {#calling-a-tool}

If Code Assistant identifies a suitable tool based on the tool descriptions, it will suggest its use. You must then approve it if [auto-approval](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/auto-approving-actions.md) is not set up for trusted tools.

### Maximizing interaction with MCP servers {#maximizing-interaction-with-mcp-servers}

By putting effort into detailed descriptions and perhaps also user instructions, you greatly improve the interaction between Code Assistant and your MCP servers. This unlocks their full potential to perform tasks more reliably and efficiently.

## Troubleshooting MCP servers {#troubleshooting-mcp-servers}

Common problems and their solutions:
* Server is not responding: Check if the server process is running and make sure you have a network connection.
* Permission errors: Make sure your API keys and credentials are set up correctly in `mcp_settings.json` for global settings or `.codeassistant/mcp.json` for project settings.
* Tool is unavailable: Make sure the server implements the tool correctly and it is not disabled in the settings.
* Slow performance: Try changing the network timeout value for a specific MCP server.

## MCP configuration examples for different platforms {#examples-of-mcp-configuration-for-different-platforms}

{% list tabs %}

- macOS/Linux

  When setting up MCP servers on macOS or Linux, you can use a simpler configuration since no Windows shell is required. Here is an example of setting up a Puppeteer MCP server on macOS or Linux:

  ```json
  {
    "mcpServers": {
      "puppeteer": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-puppeteer"
        ]
      }
    }
  }
  ```

  This configuration:
  * Directly uses `npx` without the need for a shell.
  * Employs the `-y` flag to automatically answer `yes` to any requests during installation.
  * Runs the `@modelcontextprotocol/server-puppeteer` package, which provides browser automation capabilities.

  You can adopt the same approach for other MCP servers on Windows, changing the package name depending on the server type.

- Windows

  When setting up MCP servers on Windows, use the Windows `cmd.exe` command line to run commands. Here is an example of setting up a Puppeteer MCP server on Windows:

  ```json
  {
    "mcpServers": {
      "puppeteer": {
        "command": "cmd",
        "args": [
          "/c",
          "npx",
          "-y",
          "@modelcontextprotocol/server-puppeteer"
        ]
      }
    }
  }
  ```

  This configuration:
  * Uses the `cmd.exe` command to access the Windows command line.
  * Uses `/c` to tell `cmd.exe` to run a command and exit.
  * Uses `npx` to run a package without installing it permanently.
  * The `-y` flag automatically answers `yes` to any requests during installation.
  * Runs the `@modelcontextprotocol/server-puppeteer` package, which provides browser automation capabilities.

{% endlist %}

## Configuration using runtime version managers {#configuration-with-runtime-version-managers}

When working with multiple language or runtime versions, you can use version managers such as [asdf](https://asdf-vm.com/) or [mise](https://mise.jdx.dev/) (formerly rtx). These tools help manage multiple versions of runtime environments on a single system. Here is how to configure MCP servers to work with these version managers:

{% list tabs %}

- mise

  [mise](https://mise.jdx.dev/) is a fast and up-to-date runtime version manager that you can use to specify the version of Node.js, Python, or other runtimes for your MCP server:

  ```json
  {
    "mcpServers": {
      "mcp-batchit": {
        "command": "mise",
        "args": [
          "x",
          "--",
          "node",
          "/Users/myself/workspace/mcp-batchit/build/index.js"
        ],
        "disabled": false,
        "alwaysAllow": [
          "search",
          "batch_execute"
        ]
      }
    }
  }
  ```

  This configuration:
  * Uses the `mise` command to manage runtime versions.
  * The `x` subcommand runs a command with a configured version of the runtime.
  * `--` separates the `mise` arguments and the command to run.
  * Runs `node` with a specific version configured in the `mise` settings.
  * Points to the MCP server's JavaScript file.
  * Automatically allows the `search` and `batch_execute` tools.

- asdf

  [asdf](https://asdf-vm.com/) is a popular tool for managing multiple versions of a runtime. Here is how to configure an MCP server to use a specific version of Node.js managed by `asdf`:

  ```json
  {
    "mcpServers": {
      "appsignal": {
        "command": "/Users/myself/.asdf/installs/nodejs/22.2.0/bin/node",
        "args": [
          "/Users/myself/Code/Personal/my-mcp/build/index.js"
        ],
        "env": {
          "ASDF_NODE_VERSION": "22.2.0"
        },
        "disabled": false,
        "alwaysAllow": []
      }
    }
  }
  ```

  This configuration:
  * Directly links to the Node.js executable from the `asdf` installation directory.
  * Sets the `ASDF_NODE_VERSION` environment variable to ensure the correct version is used.
  * Points to the MCP server JavaScript file.

  Using version managers ensures that your MCP servers are running the correct version of the runtime, regardless of the default version on the system, which provides consistency across environments and prevents version conflicts.

{% endlist %}

#### Useful links {#see-also}

* [What is MCP](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/what-is-mcp.md)
* [MCP overview in SourceCraft Code Assistant](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/overview.md)
* [MCP server transports: STDIO, Streamable HTTP, and SSE](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/server-transports.md)
* [Working with an MCP server SourceCraft](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/work-with-mcp.md)
* [What makes MCP different from the REST API](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/mcp-vs-api.md)
* [Recommended MCP servers](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/recommended-mcp-servers.md)