Using the MCP in SourceCraft Code Assistant

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.

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.

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

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 in the chat's top panel and select MCP servers.

2. Select the appropriate option:

   • Edit Global MCP: Opens the global file named mcp_settings.json.
   • 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:

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

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

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.

STDIO configuration example:

{
  "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

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:

{
  "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.

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.

Streamable HTTP configuration example:

{
  "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)

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.

For more information, see SSE Transport (legacy).

SSE configuration example (legacy ):

{
  "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

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. Enabled by default.

1. Click in the chat's top panel and select MCP servers.
2. Enable or disable the Enable MCP Servers option.

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. Enabled by default.

1. Click in the chat's top panel and select MCP servers.
2. Enable or disable the Enable MCP Server Creation option.

How to use Code Assistant to create an 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.

1. Articulate your request, explicitly asking Code Assistant for a new tool or feature. For 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.
2. 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.
3. 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

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 in the chat's top panel and select MCP servers.
2. In the list of MCP servers, find the one you need and perform one of the following actions.

Deleting a server

1. Click next to the MCP server you want to delete.
2. In the confirmation window, click Delete.

Restarting a server

Click next to the MCP server you want to restart.

Enabling or disabling a server

Click the toggle next to the MCP server you want to turn on or off.

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 next to the MCP server.
2. 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-approval of MCP tools works for each tool individually and is disabled by default. To set up auto-approval:

1. On the Auto-approve panel, enable MCP.
2. 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.

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 option is enabled.
• Create custom MCP servers using the SDK to extend the capabilities of Code Assistant with your own tools.

For full SDK documentation, see the MCP repository on GitHub.

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

Your interaction with MCP tools will typically follow this sequence:

1. Starting a task

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

2. Identifying a Code Assistant tool

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

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

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. 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

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 is not set up for trusted tools.

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

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

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

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

Configuration using runtime version managers

When working with multiple versions of programming languages ​​or runtimes, you can use version managers such as asdf or mise (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:

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

{
  "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": []
    }
  }
}