Example Configuration

This page shows a complete, annotated mcpls.toml that you can copy and trim. Every line that is commented out is a working option you can enable by removing the #. Each key is described in the Configuration Reference.

Save it as mcpls.toml in your user config directory, or pass its path with --config. A ./mcpls.toml inside a project is ignored unless you pass --trust-project-config (Security and Trust).

# Example MCPLS configuration file
# Copy to ~/.config/mcpls/mcpls.toml or specify with --config flag.
# If placed as ./mcpls.toml in a project directory instead, mcpls ignores it
# unless you pass --trust-project-config (or set MCPLS_TRUST_PROJECT_CONFIG=true) —
# see https://bug-ops.github.io/mcpls/advanced/security.html.

# MCP serverInfo/initialize presentation overrides (all optional; omit any
# field to keep mcpls's built-in text). `instructions` REPLACES the built-in
# capability blurb rather than appending to it. Byte caps: title 128,
# description 1024, instructions 4096 (UTF-8 bytes).
# [mcp]
# title = "My Custom Bridge"
# description = "Internal LSP bridge for Acme Corp"
# instructions = "Use get_hover before get_definition."
# tool_prefix = "optics"

# Workspace settings
[workspace]
# Root directories for the workspace
roots = [
    # Add your project paths here
    # "/home/user/projects/myproject",
]

# Position encoding preference (utf-8 is more efficient for Rust)
position_encodings = ["utf-8", "utf-16"]

# Limits (all optional; the values shown are the defaults)
# heuristics_max_depth = 10                # project-marker search depth, at most 64
# max_documents = 100                      # open documents at once, 0 disables
# max_file_size = 10485760                 # bytes, 0 disables, at most 1 GiB
# max_concurrent_server_starts = 8         # servers initializing at once
# indexing_ready_timeout_seconds = 30      # above 3 and below 60

# Language extension mappings (optional)
# mcpls recognizes 30 languages by default. Customize here to:
# - Add support for specialized file types
# - Override default associations
# - Include only languages you need

# Example: Add Nushell support
# [[workspace.language_extensions]]
# extensions = ["nu"]
# language_id = "nushell"

# Example: Override Rust detection to use custom language ID
# [[workspace.language_extensions]]
# extensions = ["rs"]
# language_id = "custom-rust"

# Default language extensions (automatically included if not specified):
# - Rust: rs
# - Python: py, pyw, pyi
# - JavaScript: js, mjs, cjs
# - TypeScript: ts, mts, cts, tsx
# - Go: go
# - C: c, h
# - C++: cpp, cc, cxx, hpp, hh, hxx
# - Java: java
# - Ruby: rb
# - PHP: php
# - Swift: swift
# - Kotlin: kt, kts
# - Scala: scala, sc
# - Zig: zig
# - Lua: lua
# - Shell: sh, bash, zsh
# - JSON: json
# - TOML: toml
# - YAML: yaml, yml
# - XML: xml
# - HTML: html, htm
# - CSS: css
# - SCSS: scss
# - Less: less
# - Markdown: md, markdown
# - C#: cs
# - F#: fs, fsi, fsx
# - R: r, R
# - JSX: jsx
# - TSX: tsx (TypeScript React)

# Rust - rust-analyzer
[[lsp_servers]]
language_id = "rust"
command = "rust-analyzer"
args = []
file_patterns = ["**/*.rs"]
timeout_seconds = 30

# Uncomment and configure as needed:

# request_timeout_seconds = 30   # each LSP request behind a tool call
# indexing = "disabled"          # opt out of indexing-readiness gating

# [lsp_servers.initialization_options]
# cargo.features = "all"
# checkOnSave.command = "clippy"

# Settings pushed after `initialized` and served on workspace/configuration
# (must not be empty)
# [lsp_servers.settings]
# "rust-analyzer.check.command" = "clippy"

# Python - pyright
# [[lsp_servers]]
# language_id = "python"
# command = "pyright-langserver"
# args = ["--stdio"]
# file_patterns = ["**/*.py"]
# timeout_seconds = 30

# TypeScript/JavaScript - typescript-language-server
# selection = "auto" starts the native TypeScript 7 server (tsc --lsp --stdio)
# when it is installed; the command and args below are the fallback.
# [[lsp_servers]]
# language_id = "typescript"
# command = "typescript-language-server"
# args = ["--stdio"]
# selection = "auto"
# file_patterns = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
# timeout_seconds = 30

# Go - gopls
# [[lsp_servers]]
# language_id = "go"
# command = "gopls"
# args = ["serve"]
# file_patterns = ["**/*.go"]
# timeout_seconds = 30

# C/C++ - clangd
# [[lsp_servers]]
# language_id = "c"
# command = "clangd"
# args = ["--background-index"]
# file_patterns = ["**/*.c", "**/*.h", "**/*.cpp", "**/*.hpp"]
# timeout_seconds = 30

# Explicit per-tool routing: run two servers for one language, each owning
# a distinct subset of MCP tools. `name` gives each server a routing
# identity (defaults to language_id, but two servers for one language must
# not share it); `handles` restricts a server to exactly those tools --
# omit `handles` for a catch-all that serves everything not claimed
# elsewhere. See https://bug-ops.github.io/mcpls/reference/config.html for the full semantics.
# [[lsp_servers]]
# name = "pyright"
# language_id = "python"
# command = "pyright-langserver"
# args = ["--stdio"]
# file_patterns = ["**/*.py"]
#
# [[lsp_servers]]
# name = "pylsp"
# language_id = "python"
# command = "pylsp"
# file_patterns = ["**/*.py"]
# handles = ["diagnostics"]

What’s Next

Learn what each key does in the Configuration Reference, or return to Configuration for a guided walkthrough.