Connect MCP servers

MCP servers give Embedder extra tools, such as issue trackers, documentation search, or a program that controls your test bench. Add a server from the catalog or your own, then choose which of its tools Embedder can use and which ones control hardware.

Embedder calls MCP tools without asking for approval, whatever your approval settings, and the tools are available in every mode, including Plan. Before you connect a server, review what its tools can do and what access it requests. Turn off any tool you don’t want Embedder to call. See Choose which tools Embedder can use.

Add a server from the catalog

The catalog includes these servers:

Server	What you need
GitHub	A GitHub personal access token.
Linear, Notion, Sentry	Browser sign-in.
Firecrawl	A Firecrawl API key, and Node.js for `npx`.
Asana	An Asana OAuth client ID and client secret, Node.js for `npx`, and browser sign-in.
Atlassian (Jira and Confluence)	Node.js for `npx`, and browser sign-in.

Catalog servers and the credentials you enter are saved in plain text in your global configuration, ~/.embedder/mcp.json. To keep a secret out of the file, enter ${NAME} as the credential and set the NAME environment variable instead. See Credentials.

VS Code
Terminal UI

Run /mcp in chat. The MCP Servers panel opens.
Select Browse, then select Install next to the server.
If the server needs credentials, enter them on the Configure screen and select Install & connect.
Complete any browser sign-in the server asks for.

Run /mcp. The MCP Servers list opens.
Press m to open Browse MCP Servers.
Select a server with the arrow keys and press Enter.
If the server needs credentials, enter them on the Configure screen and press Enter on the last field.
Complete any browser sign-in the server asks for.

After it connects, the server shows Connected and its tool count. Ask Embedder to run a small read-only check, such as listing recent issues, before you use tools that change data.

Add your own server

Use a custom server for a local program, such as a bench controller, or for a remote MCP endpoint.

VS Code
Terminal UI
Command line

Run /mcp and select Add custom.
Enter a Name.
Choose a Transport: stdio for a local program, or http or sse for a remote server.
Enter the Command (for example, npx -y my-mcp-server) or the Endpoint URL.
Select Add & connect.

To add environment variables or headers, use the command line or edit the configuration file. See Choose a configuration scope.

Run /mcp and press a. The Add Custom Server form opens.
Enter a Name. Press Enter to move to the next field.
On Transport, press ← or → to choose stdio for a local program, or http or sse for a remote server.
Enter the Command (for example, /opt/board-tools/board-mcp --port /dev/ttyACM0) or the Endpoint URL.
Optionally, enter environment variables in Env (optional), or headers in Headers (optional), as comma-separated KEY=VALUE pairs.
Press Enter on the last field to add the server and connect.

Add a local program:

embedder mcp add board-tools /opt/board-tools/board-mcp --scope project

Add a remote server:

embedder mcp add lab https://lab.example.com/mcp --transport http --scope project

Use --transport sse only when the server requires SSE. Run project-scope commands from the project root. See MCP commands for every option.

Servers you add from /mcp are saved in your global configuration. Use embedder mcp add --scope project or edit .embedder/mcp.json to share a server with everyone who works on the project.

Local programs

The program and everything it depends on must be installed on the machine that runs Embedder. Use an absolute path if the program is not on PATH. In VS Code, the program starts in the workspace folder. In the terminal UI, it starts in the folder where you started Embedder. A local server receives only basic variables, such as PATH and HOME, from your environment. Pass anything else it needs explicitly:

embedder mcp add board-tools /opt/board-tools/board-mcp \
  --env 'BENCH_ID=lab-3' --env 'BENCH_TOKEN=${BENCH_TOKEN}'

Each tool call times out after 60 seconds unless the server reports progress while it works. Keep long operations, such as a full flash, within that limit or have the server report progress.

Credentials

Keep secrets out of shared configuration. Write ${NAME} in a header, environment value, URL, command, or argument, and Embedder replaces it with the environment variable when it connects. ${NAME:-fallback} uses the fallback when the variable is not set or is empty.

embedder mcp add lab https://lab.example.com/mcp \
  --transport http --scope project \
  --header 'Authorization=Bearer ${LAB_MCP_TOKEN}'

Use single quotes so your shell does not replace the variable first. Set the variable in the environment that starts Embedder or VS Code. If it is missing and has no fallback, the server fails to connect with Environment variable "NAME" is not set and has no default value. For a server that uses browser sign-in, connect from /mcp. Embedder opens your browser to authorize the server, and the sign-in times out after 2 minutes. Browser sign-in needs a browser on the machine that runs Embedder.

Choose which tools Embedder can use

Run /mcp and open a server to turn it, or any one of its tools, on or off.

VS Code
Terminal UI

Select a server on the Installed tab. Its details show the connection, any credentials, and its Tools. The tool list appears while the server is connected.

Control	What it does
Server switch	Turns the whole server on or off. A server that is off stays in your configuration but is disconnected.
Retry	Reconnects the server. It appears next to the error when a connection fails.
Edit	Changes a catalog server’s credentials, under Credentials. Select Save & connect when you finish.
Enabled	Shows or hides one tool from Embedder. The summary shows how many of the server’s tools are enabled.
Hardware	Marks a tool that flashes, resets, captures from, or otherwise controls a live target.
Remove	Deletes the server from your global MCP configuration.

In the MCP Servers list, select a server and use these keys:

Key	Action
`Enter`	Connect or disconnect the server.
`r`	Reconnect the server.
`d`	Turn the server on or off.
`i` or `→`	Show the server’s details and tool list.
`m`	Open the catalog.
`a`	Add a custom server.

In the server’s details, use these keys. The tool list appears while the server is connected.

Key	Action
`↑` or `↓`	Select a tool.
`Space`	Show or hide the selected tool from Embedder.
`h`	Mark the selected tool as a hardware tool, or clear the mark. Hardware tools show `[hw]`.
`c`	Edit a catalog server’s credentials.
`x`	Remove the server from your global MCP configuration.

Changes you make in /mcp are saved to your global configuration. For a server defined in .embedder/mcp.json, edit that file instead. Subagents can use only the tools that a server marks as read-only. General subagents can also use the tools you mark as hardware tools, unless you turn off their hardware access with /subagent-hardware.

Mark hardware tools

Mark every tool that controls a live target as a hardware tool. Embedder then lets one session or subagent use the board at a time, and the others wait until it is free, as with Embedder’s own hardware tools. Marking a tool doesn’t add an approval prompt. The setting does not check what the external program does. Confirm that the tool targets the intended device, and review its actions before you run a hardware workflow.

Choose a configuration scope

Scope	File	Use it for
Global	`~/.embedder/mcp.json`	Servers you use in every project. Servers added from `/mcp` go here.
Project	`.embedder/mcp.json`	Servers the whole project should share.

When both files define a server with the same name, the project entry replaces the global one.

Servers in a project’s .embedder/mcp.json connect automatically, and local programs start, when you chat in that project. Embedder doesn’t ask first. Review this file in any repository you clone before you use Embedder in it.

The file uses the same server format as other MCP clients, so you can paste a block from another client’s configuration. Embedder reads servers under servers or mcpServers. When type is missing, an entry with command is stdio and an entry with url is http, so set "type": "sse" for an SSE server.

.embedder/mcp.json

{
  "servers": {
    "board-tools": {
      "type": "stdio",
      "command": "/opt/board-tools/board-mcp",
      "env": { "BENCH_TOKEN": "${BENCH_TOKEN}" },
      "enabled": true,
      "disabledTools": ["erase_board"],
      "hardwareTools": ["flash_board", "capture_trace"]
    },
    "lab": {
      "type": "http",
      "url": "https://lab.example.com/mcp",
      "headers": { "Authorization": "Bearer ${LAB_MCP_TOKEN}" }
    }
  }
}

Field	Applies to	Meaning
`type`	All	`stdio`, `http`, or `sse`.
`command`, `args`	`stdio`	The program to start and its arguments.
`env`	`stdio`	Environment variables passed to the program.
`url`	`http`, `sse`	The server address.
`headers`	`http`, `sse`	Request headers, such as `Authorization`.
`enabled`	All	`false` keeps the server configured but disconnected.
`disabledTools`	All	Tool names to hide from Embedder.
`hardwareTools`	All	Tool names that control a live target.

Embedder ignores any other fields and removes them the next time it saves the file. Use tool names from the server’s actual tool list, as shown in its details in /mcp. If the file isn’t valid JSON, for example because it has comments or a trailing comma, Embedder renames it to mcp.json.corrupt.<timestamp> and continues without it. If one server entry is invalid, Embedder ignores the whole file. Fix the file and reconnect.

Remove a server

In VS Code, open the server in /mcp and select Remove. In the terminal UI, open the server’s details with i and press x. Both remove servers in your global configuration, right away and without asking you to confirm. To remove a server in the project configuration, use the command line from the project root:

embedder mcp list
embedder mcp remove board-tools --scope project

embedder mcp remove uses global scope unless you add --scope project.

Troubleshoot

Symptom	What to check
A local server shows a command not found	Install the program, or use its absolute path.
A local server starts but fails to authenticate	Pass the variables it needs with `--env` or `env`. It does not inherit your full environment.
A variable is reported as not set	Set it in the environment that starts Embedder or VS Code, then reconnect.
Remote sign-in does not finish	Reconnect from `/mcp` (Retry in VS Code, `Enter` in the terminal UI) and complete the browser prompt on the machine that runs Embedder within 2 minutes.
A credential is rejected	Update the header, environment variable, or catalog credential, then reconnect.
A tool is missing	Check that the server is connected and turned on, and that the tool is not in `disabledTools`. A subagent sees only read-only tools and, for general subagents, hardware tools.
A server from `.embedder/mcp.json` disappeared	Check the file for invalid JSON or an invalid entry. See Choose a configuration scope.
A tool call times out	The call took longer than 60 seconds without reporting progress. Shorten the operation or have the server report progress.
TLS certificate verification fails	Install your company’s certificate authority in the operating system trust store, or set `NODE_EXTRA_CA_CERTS` to its PEM file before you start Embedder. For a local program that connects to the remote service itself, such as the Asana or Atlassian catalog server, add `NODE_EXTRA_CA_CERTS` to that server’s `env`. Then reconnect.

Get started

Set up a project

Work with Embedder

Workflow guides

Monitor and debug

Code analysis

Automation

Settings and help

Reference

Connect MCP servers

Add a server from the catalog

Add your own server

Local programs

Credentials

Choose which tools Embedder can use

Mark hardware tools

Choose a configuration scope

Remove a server

Troubleshoot