Local MCP servers

This is about servers **you** add. There is no MatchaCode catalog to browse, no managed MCP gateway, and no official cloud of connectors.

Add a local (stdio) server

The usual first server is a local process. Matcha CLI launches it and talks over stdin/stdout.

From the project directory, or from anywhere for a user-wide server:

matcha mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

Everything after -- is the server command, so flags such as -y reach the server, not matcha.

Give the process environment with repeatable -e:

matcha mcp add postgres -e DATABASE_URL=postgres://localhost/mydb -- npx -y @modelcontextprotocol/server-postgres

Default scope is **user** (~/.matcha/config.toml). Use --scope project to write ./.matcha/config.toml in the current directory (shareable with the team).

Server names may contain only letters, numbers, hyphens, and underscores.

Equivalent TOML:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
enabled = true

Point at a remote server you already have

If a third-party host publishes an HTTP or SSE MCP endpoint, you can add **that URL**. This is not a MatchaCode product service.

matcha mcp add --transport http sentry https://mcp.sentry.dev/mcp
matcha mcp add --transport sse linear https://mcp.linear.app/sse

Repeat --header "Name: value" for static auth. Prefer ${VAR} in committed project config instead of pasting a secret:

[mcp_servers.internal-tools]
url = "https://mcp.internal.example.com/mcp"
headers = { "Authorization" = "Bearer ${INTERNAL_MCP_TOKEN}" }

OAuth for a **user-configured** remote server is allowed. After you add the server, open /mcps and press i on that row if the host asks you to sign in. Tokens land in ~/.matcha/mcp_credentials.json (owner-only permissions on Unix). There is no MatchaCode account in this flow.

List, enable, disable, remove, doctor

matcha mcp list
matcha mcp list --json
matcha mcp enable filesystem
matcha mcp disable filesystem
matcha mcp remove filesystem
matcha mcp doctor
matcha mcp doctor filesystem

• list shows user and project servers. Project rows are marked (project); disabled rows are marked (disabled).
• remove searches both scopes. It exits 1 if the name is missing, or if the same name exists in both scopes — pass --scope to choose.
• enable / disable persist your personal on/off state in user ~/.matcha/config.toml. Disable never rewrites a project file. Enable can clear a sticky enabled = false on the nearest project definition.

In the TUI: `/mcps`

/mcps

That opens the extensions modal on the **MCP Servers** tab. Outside the VS Code family you can also press Ctrl+L and switch to that tab.

MCP tools are namespaced: server github with tool create_issue becomes github__create_issue. The assistant finds them with search_tool and calls them with use_tool.

Project `.mcp.json` and other tools

Matcha CLI also **reads** MCP configs it did not write:

When names collide, the higher source wins: config.toml > Claude > Cursor > .mcp.json. Turn a vendor scan off with [compat.cursor] mcps = false or MATCHA_CURSOR_MCPS_ENABLED=false (and the Claude equivalents).

matcha inspect lists every loaded server and tags the vendor origin ([cursor], [claude]).

Project .matcha/config.toml is walked from cwd up to the git root. The deepest file wins. A same-named project server **replaces** the user server entirely (fields are not merged).

What is not available

• **MCP marketplace** — there is no catalog to install from.
• **Managed MCP gateway** — no managed_gateway:… connectors. Those stay out of /mcps and matcha mcp enable / disable.

If a server will not start, run its command yourself, then check ~/.matcha/logs/mcp/<server>.stderr.log. matcha mcp doctor and matcha inspect show what was configured versus what connected.

What you should see