Estimate project
← All posts

Getting Started with Scala Metals and Its Model Context Protocol Server

Boost agent-assisted Scala development with the Metals MCP server, which supplies the context AI needs to produce high-quality code.

7 min read
ScalaAIMetalsScala ProgrammingMCPAgents

In AI-assisted software development, AI agents are the next big thing.

Chances are you’ve at least experimented with copilot-style code completions or copilot-powered edit suggestions to fix specific issues in your codebases. Agents go a step further: they take charge of drawing up an action plan, editing files, executing shell commands, and so forth. All of this happens in reaction to your initial prompt, the subsequent conversation, and the feedback they receive from carrying out their actions.

Yet an agent can only be as good as the context available to it. Of course, that covers the project files and the prompt, but at times this just isn’t the full picture. This is where MCP helps: it lets the AI model produce calls to external systems. And since it’s a standard (originating at Anthropic and now embraced by Microsoft, Google, and many others), one MCP server can work with Gemini, Claude, and GPT models alike.

An MCP server can expose virtually any functionality, from fetching the weather, through talking to external systems like GitHub, to querying information available locally through the build system. A prime example is Scala’s Metals server, which can not only compile the project but is also what IDEs rely on for code completions, type checking, symbol inspection, etc. The newly introduced Metals-MCP integration makes this information available to AI models.

You can also view MCP servers as an addition to the built-in tools that agents already have (supplied by the creators of Copilot’s agent mode or the Cursor IDE). Those built-in tools cover things like reading a file’s contents, editing a file, or executing a shell command. Extra MCP servers, such as the Metals one, broaden this to inspecting Scala symbols, compiling the codebase, or running tests. The agents’ textual responses can then contain calls to both built-in and additional tools.

Configuring Metals MCP

I’m assuming you already have a Scala project with the Metals plugin installed. If you don’t, a good starting point could be to generate a simple HTTP API project from a template, install the Metals plugin from the VS Code marketplace, and import the build into the IDE. If you run into trouble, check the Metals docs!

Actually, just installing Metals and importing the build will already get you a long way with agents – see the linting integration below (that is, the warnings and errors Metals reports in your source files). MCP tools add further capabilities on top of that.

In Visual Studio Code

Open Settings and look up “MCP”. You need to turn on MCP in VS Studio Code in general as well as the Metals MCP server in particular:

As an alternative, you can switch on these two settings in your config file:

"chat.mcp.enabled": true
"metals.startMcpServer": true

Once you open a project with Metals enabled, the following popup should appear (your port will most likely be different):

Next, open Copilot Chat and pick the “Agent” mode:

The stack icon (third from the left) stands for “new tools found” – click it to go through them. By clicking the second tooling button from the left, you can also choose which tools will be used:

Configuring Metals MCP in Cursor

Start by going to Settings -> VS Code Settings and looking up the metals.startMcpServer setting (e.g. using the search). Turn it on so the MCP server gets started:

Cursor should then detect the new MCP server automatically and offer to add it to your configuration:

If that doesn’t happen, open Settings -> Cursor Settings -> MCP Tools and check the list. If it’s empty, add a new MCP Server by hand, which should open mcp.json for you. Its content should look roughly like this:

{
  "mcpServers": {
    "chimp-metals": {
      "url": "http://localhost:57525/sse"
    }
  }
}

The port varies from one installation to another; you’ll find yours under the Metals tab -> Check logs:

2025.06.05 10:40:52 INFO  Metals MCP server started on port: 57525.

Once that’s added, the MCP server should show up as working and list the 9 tools that the Metals MCP server exposes at the moment:

Using Metals MCP

Time to put it to good use. Open the agent chat (the AI Pane in Cursor, Copilot Chat in VS Code) and hand the agent a task. Be sure to pick the “Agent” mode rather than “Ask”! (The latter is the default in VS Code.)

In my case, I was trying out writing an MCP server in Scala (from scratch). For that, I first had to convert the data model defined in TypeScript into Scala – a fairly mechanical job, ideal for an AI assistant.

This is the prompt I started with (a small piece of the model was already defined from earlier experiments):

Cursor uses some of its built-in tools (web search, reading the Tools.scala file) to work out an action plan. You can then observe it refine a design, producing the model classes over a few iterations.

Whenever generated code leads to a compile error, Metals spots it and reports it as a regular “linter error”:

Once the agent notices an error, it tries to fix it on its own, producing the next version of the code and linting it (that is, compiling it and getting feedback from the Metals compile server). Eventually, though, it does give up and asks you to step in!

At times, you’ll notice the agent explicitly calling the MCP tools to compile the code it has generated:

At other times, it will resort to running sbt compile through a shell command:

Keep in mind that ultimately, the commands to run are generated by the LLM. It may produce a request to invoke an MCP tool, but it may just as well decide that this time it’ll go the old-fashioned way!

You can decide whether linter errors and MCP tools are invoked automatically or require your approval. VS Code always asks before it runs an MCP tool. In Cursor, you can set this per tool in the settings, but by default it uses the available tools automatically (in contrast to VS Code). Quite often, the LLM will also come up with questions that need your input and approval, e.g., when a particular course of action has to be chosen. That’s independent of approving MCP tool runs.

Agents & Scala 3

Agents do a pretty good job at generating Scala code, and the fast feedback loop they get from the compiler (through linters or MCP tools) makes it even better. Still, most of the generated code tends to be Scala 2-style: from the import syntax, through “braceful” syntax, to implicits in place of givens, and sealed traits in place of enums.

As a result, you’ll frequently need to ask explicitly for Scala 3 code – and even so, you may still get Scala 2 code. In that case, simply ask once more for a refactor to Scala 3 style or for sealed traits to be swapped for enums, and you’ll get nearer to what you want. Automatic formatting with scalafmt (which can rewrite braces if configured to) takes care of the rest.

Agents can accomplish a lot, but ultimately they still require plenty of supervision, and you have to know your Scala (or whichever language you work in) to get good results!

Lend the Metals team a hand!

How effective an MCP server is depends largely on how good the tool descriptions are, and on which tools are exposed to begin with. Expose too many, and the LLM may get overwhelmed and pick the wrong one. Too few, and the functionality simply isn’t available. If you have ideas for the Metals team, I’m certain they’d welcome your feedback!

Take a look at the current MetalsMcpServer definition (search for new Tool(...) calls). Prompt engineering is turning into a discipline of its own, and Cursor illustrates this well. An AI-first IDE is only as strong as the prompts it uses. So contributions can include not just new tools, but better prompts too!

Based on my (still very limited) experience, compile-file is by far the most used tool. When searching, the LLM still typically falls back on grepping the codebase. Getting the model to use, e.g., the find-usages tool requires being very explicit:

You could argue that the old-fashioned Go To References action in the IDE does the same – faster & cheaper. The aim, however, is for the model to rely on these tools in more complex tasks carried out autonomously. Perhaps the descriptions of these tools need to be refined, or perhaps the tasks I’ve run so far simply didn’t call for such functionality.

Further experiments are needed – please share your results! :)