Manage MCP ServersCopy Anchor Link

The MCP page manages a local configuration library and can apply server configurations to detected local Agents it supports. A check mark means the configuration was written; it does not mean the MCP server is running or its tools are available. Prepare the required runtime, command, and credentials separately.

Add and apply an MCP serverCopy Anchor Link

1. Open MCP from the desktop app sidebar. If no supported Agent is detected, you can still save a configuration in the local library. Visit Agents to inspect local installations.
2. Select Add MCP and enter an identifier and display name. Choose a transport: local command (stdio), HTTP, or SSE. Transport support depends on the target Agent. Codex, Grok Build, and Pi do not support SSE; use Streamable HTTP for those Agents.
3. For a local command, enter an installed executable, one argument per line, an optional working directory, and any required environment variables. For HTTP or SSE, enter a URL and any required headers. You can also switch to Edit JSON. Templates only fill configuration fields; they do not install a server or its dependencies.
4. Select the Agents to configure. Leaving them all unchecked saves the entry to the local library only. Review the destination paths, command, arguments, and transport compatibility for each selected Agent. Check credentials in environment variables, URLs, and headers carefully; follow the compatibility result shown by the client.
5. Select Preview changes, check which Agents will be changed, then confirm. After success, the MCP table shows Configured for the selected Agent. Restart the Agent if it has not loaded the new configuration.
6. Call an MCP tool from the target Agent to confirm the server responds. Configured in the MCP table only means configuration was written; it is not a connectivity test.

Import an existing configurationCopy Anchor Link

Import from an Agent: Select Import, check existing entries under a detected Agent, and select Preview import. This reads the existing configuration. After importing it into your local library, select a target Agent and preview the change to have Lumoswitch manage it. The import dialog marks entries already in the library.

Paste a configuration: Select Paste, then paste JSON, Codex TOML, or OpenCode configuration. Review the entries found and select which ones to import. An entry with the same name replaces the local library entry; this does not automatically overwrite an Agent's files. You can also select Agents to apply the imported entries in this flow. Agent-specific fields cannot be replaced here; edit them in the original Agent.

Opening a lumoswitch-mcp: import link places its configuration in the paste flow. Review the entries and target Agents, then preview and confirm the changes.

Edit, enable, and disableCopy Anchor Link

• Select an MCP name in the list to edit it. Use the Agent checkboxes to enable a connection, or select an Agent column heading to manage entries in bulk. When a search or filter is active, bulk actions apply only to the current results.
• A check mark means a managed configuration is written. A changed or conflict state means an update needs syncing or a name conflicts. Unsupported, read-only, and unresolved targets cannot be safely written. Open the entry to see its message and path.
• Disabling removes a Lumoswitch-managed connection. Deleting from the library removes only the local library entry and keeps Agent configuration. Removing from all managed Agents deletes managed connections from those Agents. Check the action and targets before confirming.
• If an operation has failures, inspect the result panel and retry failed items. If an Undo action is available, use it to reverse the change.

Credentials and troubleshootingCopy Anchor Link

• Environment variable and header values are hidden by default. Existing credentials are not shown in plain text, and sensitive values remain masked in JSON editing. Avoid revealing, copying, or sharing real credentials unless needed.
• A local command must already be installed and executable in the target Agent's environment. An HTTP/SSE server must be reachable by that Agent. Lumoswitch saves and applies configuration; it does not install every external program or server dependency.
• A target is read-only or shows an error: Expand its message to check the configuration path, version, or custom directory. Recheck the installation from Agents. Do not overwrite a file with external changes or a conflict.
• Import finds no entries: Check that the content is JSON, Codex TOML, or OpenCode configuration with valid MCP entries. Some Agent-specific configuration must be edited in that Agent.
• The entry is configured but its tools do not work: Check the command, arguments, working directory, URL, headers, and environment variables. Confirm the server is installed and reachable, restart the Agent if needed, then call the tool inside the Agent.
• A library entry is not in the Agent: If no target Agent was selected when saving, the entry is only in the local library. Edit it or use bulk management to apply it to a target.

Related guidesCopy Anchor Link

• Desktop overview
• Agents
• Skills
• Help and troubleshooting