Custom MCP

Custom MCP connects additional Model Context Protocol servers to Luna. Newly discovered tools default to the Read-only category and are enabled for bound apps. Review their actual behavior and assign write or high-risk tools to the appropriate category before use. A category controls Soln’s execution policy; it does not change what the upstream tool can do.

Open Luna, then select Agent Settings > Custom MCP.

Before You Add A Connection

• A remote MCP server must be reachable from the tenant runtime, so check the network zone and the address first
• Credentials and environment variables are stored encrypted and are never shown again, so keep your own copy before installing
• Only install MCP servers you trust: their tools run with the permissions of the runtime

Add An MCP Connection

1. Choose Add MCP and pick the source: a remote HTTPS MCP address, a local command, or a Docker image. An mcpServers JSON block can be pasted as well
2. Fill the configuration:
   • Remote: name, description, HTTPS MCP address, network zone, and the authentication type (Bearer token or API key header)
   • Local: name, description, command or Docker image, start arguments as a JSON array, and environment variables as a JSON object
3. Review the network and credential permissions, then install. Credentials and environment variables are encrypted in the tenant database and are never shown again
4. Follow the installation log: configuration saved, runtime starting, tool catalog syncing, connection activating, and finished or failed
5. Open Manage tools to review tool names, descriptions, categories, and enabled states. Only enabled tools are available to the agent
6. Share the connection with the workspace or keep it private, bind it to the app, or uninstall it when it is no longer used

Verify The Connection

1. Wait for the installation log to reach the completed step
2. Open Manage tools and confirm the discovered tools are listed with their risks
3. Check which tools are enabled, disable any the app should not use, then ask the agent in the app conversation to run one. The conversation displays the tool call and its execution result
4. If the tool list is out of date, sync the catalog again after the MCP server is reachable

Tool Management

The left menu contains All tools, Read-only, Write, and High risk. There is no unclassified category.

• Search the current list by tool name or description and press Enter; clear the search to restore the list.
• Use the Enable or Disable text button on a tool row to change its availability.
• Click a row to open its details: name, description, input Schema, and output Schema when provided. Schemas appear in a code panel with a copy button.
• To change categories, click + beside the target category. The popover lists all tools, with colored tags for their categories. Search with Enter, select multiple tools, then choose Add to move them to the target category. Close dismisses the popover without applying the selection.
• Category changes are managed by the app that owns the MCP connection. Changing a category does not enable a disabled tool.

When upgrading from a version with unclassified tools, the database migration assigns tools without an administrator category override to Read-only, retains explicit administrator categories, and enables newly added selections for active bindings. Existing disabled selections remain disabled.

Uninstall

Uninstalling removes the connection from the app. A connection that is shared with the workspace cannot be uninstalled while other apps still bind it; unbind it from those apps first.

Troubleshooting

Symptom	What to check
Import of mcpServers JSON fails	The JSON must contain a mcpServers object with exactly one server; args must be a string array and env an object of strings. Remote imports support a single Bearer or API key header
Installation failed	Open the installation log and read the failing step, then correct the address, credentials, or command
Tool catalog does not update	Sync the catalog again or check that the MCP server is reachable from the runtime
Operation times out	Installation and tool operations run against the MCP server; retry after checking the upstream service