Troubleshooting

This section covers common issues you might encounter while using OneServer and suggests potential solutions.

Issue: Client Application Not Detected

• Symptom: An installed MCP-compatible application (like Cline or Claude Desktop) doesn’t appear in the “Clients” list in the sidebar.
• Solutions:
  • Refresh List: Click the Refresh icon () next to the “Clients” heading in the sidebar. This forces OneServer to re-scan for known client configuration files.
  • Check Client Installation: Ensure the client application is properly installed in its default location. OneServer looks for specific configuration file paths.
  • Unsupported Client: OneServer currently only automatically detects clients with known configuration paths (e.g., Cline, Claude Desktop on macOS, Windows, Linux). Other clients might not be detected automatically. Support for more clients may be added in the future.
  • Permissions: Ensure OneServer has the necessary permissions to read the user directories where client configurations are stored (usually within your home directory).

Issue: “Install OneServer Connector” Fails

• Symptom: Clicking the “Install OneServer Connector” button results in an error toast, and the client status remains “Detected” or changes to “Error”. An error event might appear in the System Events feed.
• Solutions:
  • Check Permissions: OneServer needs permission to write to the client application’s configuration file. Ensure the file isn’t read-only or locked by another process. On some systems, you might need to run OneServer with elevated privileges (though this should generally be avoided if possible).
  • Corrupted Config File: The client’s configuration file might be corrupted or improperly formatted. Try backing up and resetting the client’s configuration if possible.
  • Review System Events: Check the payload of the client.connector.install.failed event in the System Events feed for a more specific error message.

Issue: Server Discovery Fails or Times Out

• Symptom: Clicking “Discover Resources” results in an error toast (“Discovery Failed”, “Discovery Timed Out”), the button stops spinning without populating the “Discovered Resources” panel, or an error appears below the button.
• Solutions:
  • Check Server Status: Ensure the MCP server you are trying to discover is actually running.
    • For Stdio servers: Verify the Command is correct and can be executed successfully in your terminal. Check if the process started and didn’t immediately crash.
    • For SSE servers: Ensure the URL is correct and the server is reachable over the network. Try accessing the URL in a browser or using curl.
  • Check Configuration: Double-check the Command (including paths and arguments) or URL. Ensure any required Environment Variables (like API keys) are correctly entered.
  • Firewall/Network: For SSE servers, ensure no firewall is blocking the connection to the specified URL and port.
  • Timeout: If you get a timeout error, the server might be slow to respond. You can try again later. If it persists, the server might be overloaded or have an issue (default timeout is 30 seconds).
  • OAuth Issues (SSE): If an SSE server requires OAuth and the automatic flow fails (e.g., browser popup blocked, callback issue), discovery will fail. Check system events for authentication-related errors.
  • Review System Events: Look for server.discovery.failed or server.discovery.timeout events for potential error details in the payload.

Issue: Cannot Save a Manually Added Server

• Symptom: The “Save” button is disabled or clicking it shows a validation error like “At least one capability… must be discovered before saving.”
• Solution: You must successfully run the “Discover Resources” step for manually added servers before you can save them. Ensure discovery completes without errors and populates the “Discovered Resources” panel with at least one item (Tool, Prompt, Resource, etc.).

Issue: Client Cannot Access an Associated Server

• Symptom: You’ve added a server and enabled its association toggle for a configured client, but the client application still cannot use the server’s capabilities.
• Solutions:
  • Verify Client Status: Ensure the client’s status in OneServer is “Configured” (blue indicator). If it’s “Detected” or “Error”, the connector isn’t properly installed or active. Re-install the connector.
  • Verify Association: Double-check that the toggle switch for the desired server is ON in the client’s “Associated Servers” list (in View mode).
  • Restart Client: Sometimes, client applications need to be restarted after the connector is installed or server associations are changed to pick up the new configuration.
  • Check OneServer Logs: Look at the System Events feed in OneServer for any errors related to the gateway or proxy when the client tries to make a request.
  • Check Server Status: Ensure the MCP server itself is running and functional. Try discovering its resources again within OneServer using the button in the Server Details view.