L2 · 09 · Using & Configuring MCP Servers

Level 1 explained what MCP is and built a toy server. This page is the practitioner's guide: when an MCP server is worth adding, how to find trustworthy ones, how to configure them in your IDE and CLI agents (with secrets done right), Metals MCP for Scala in depth, and how to troubleshoot.

Do you even need an MCP server?

Finding servers and judging trust

Places to look: the official MCP Registry (registry.modelcontextprotocol.io, a public catalogue of server metadata), the vendor of the system you want to connect (official servers are best), your IDE's marketplace or MCP gallery, and well-known open-source projects.

• Publisher: is it from the system's vendor or a reputable org? Name-squatting exists.
• Source available and maintained: recent commits, issues answered, a clear licence.
• Permissions: what can its tools do? Read-only modes? Scoped tokens?
• Tool descriptions: read them, since manipulative instructions hidden there are an attack ("tool poisoning").
• Pinned versions: install a specific version rather than "latest" so it can't change under you.
• Data flow: for remote servers, where does your data go, and is it allowed by your company's policy?

Configuration recipes

VS Code (workspace: .vscode/mcp.json)

{
  "inputs": [
    { "id": "dbUrl", "type": "promptString", "description": "Read-only dev database URL", "password": true }
  ],
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@<pinned-version>"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "orders-db": {
      "type": "stdio",
      "command": "<trusted-postgres-mcp-server>",
      "args": ["--read-only"],
      "env": { "DATABASE_URL": "${input:dbUrl}" }
    }
  }
}

• inputs prompt you once for secrets and store them securely, so the file never contains them.
• Remote servers that support OAuth open a browser sign-in. The host stores the token.
• User-level config (your profile) is for personal servers. Workspace config is for the team. Commands in the Command Palette start with "MCP:" (add, list, start/stop, show output).

CLI agents

# stdio server (local process)
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@<pinned-version>
codex  mcp add playwright -- npx -y @playwright/mcp@<pinned-version>

# remote server (HTTP)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# inspect
claude mcp list
codex  mcp list

CLI agents also store servers in config files (user-level and/or project-level). Project-level files can be committed when they contain no secrets. Pass secrets through environment variables.

Other hosts

• JetBrains IDEs: the AI settings include an MCP section to add servers (same fields: name, command/URL, env), and JetBrains IDEs can expose IDE tools to external agents.
• Xcode: acts mainly as a server: enable "Allow external agents to use Xcode tools" and connect agents via xcrun mcpbridge (Level 1 page 06).
• Chat desktop apps: usually an mcpServers JSON block or a connectors UI.

Metals MCP for Scala, in depth

Metals already gives agents compiler diagnostics (the red squiggles) in editors that surface them. The MCP server goes further and lets agents actively ask the Scala tooling.

1. VS Code: set "metals.startMcpServer": true (and enable MCP/agent mode). Metals logs a line like "Metals MCP server started on port …" and can write the MCP config for supported editors.
2. Other editors / CLI agents: point the agent at the URL Metals prints, or use the standalone metals-mcp launcher (install with Coursier: cs install metals-mcp) with your workspace path.
3. Teach the agent to use it. Add this to AGENTS.md:

## Scala tooling
- Use the Metals MCP tools to inspect symbols and read docs before using an unfamiliar API.
- After editing, compile the changed module with the Metals compile tool; fix all errors before running tests.
- Prefer the Metals test tool for single suites; run `sbt test` only for the final check.

Useful server categories

Keep toolsets small

Every enabled tool's name, description and schema is sent to the model on every request. Twenty servers with 300 tools cost tokens, slow responses and confuse tool choice.

• Enable servers per workspace or per task, not globally "just in case".
• Disable individual tools you don't need (most hosts have a tool picker).
• Give custom agents their own toolsets (page 08). The reviewer doesn't need the browser.
• Keep approval on for writes, deletes and anything that sends data out.

Troubleshooting

npx @modelcontextprotocol/inspector <command> <args...>
# e.g. npx @modelcontextprotocol/inspector uv run word_tools.py