oneserver Logo
oneserver
Getting Started

Getting Started

This guide will walk you through launching the application for the first time, understanding the interface, and performing the initial setup steps to connect your applications and MCP servers.

Launching OneServer

After installing OneServer (see Installation), launch the application.

Interface Overview

Upon first launch, OneServer presents its main interface:

  1. Left Sidebar (Navigation):

    • Shows expandable sections for Servers (initially empty, categorized into STDIO and SSE) and Clients.
    • Crucially, OneServer automatically scans for known compatible client applications (like Cline, Claude Desktop) on launch. Any detected clients will immediately appear under the “Clients” section, typically with an orange Detected status. You can manually re-scan using the Refresh icon ( ) next to “Clients”.
    • Provides ”+” buttons next to STIDO and SSE to manually add new servers.
    • Includes a “Settings” button at the bottom.
    • Can be collapsed/expanded using the / button.

  2. Main Dashboard Area:

    • The central area initially shows:
      • Discover Servers: This panel displays pre-configured MCP server templates (like “Sequential Thinking” or “Slack Integration”) fetched on launch. You can easily add these with a click.
      • System Events: A log showing OneServer’s startup actions and subsequent events. This feed updates in real-time.
    • Both panels can be collapsed/expanded using the / icon in their headers.

  3. Right Detail Panel:

    • This panel is initially hidden. It appears on the right when you select an item (Server, Client, Event) from the sidebar or dashboard, or when you click “Settings”.
    • It displays details and provides actions/forms related to the selected item. Close it with the “X” button.

Understanding Client Status

Detected clients listed in the sidebar have a status indicator:

  • Detected: The client application’s configuration file was found, but OneServer is not yet managing its MCP connections.
  • Configured: You have installed the OneServer Connector for this client. OneServer is now proxying its MCP traffic.
  • Error: There was a problem installing or communicating with the connector for this client.

Installing the OneServer Connector (Essential First Step)

To make a detected client application use OneServer, you must install the connector:

  1. Select Client: Click on a client listed under “Clients” (e.g., “Cline”). It should have the orange “Detected” status.
  2. View Details: The Right Detail Panel will open, showing “Client Details”.
  3. Click Install: At the bottom of the panel, click the “Install OneServer Connector” button ( icon).
  4. Confirmation: OneServer modifies the client’s config file. The client’s status indicator will change to blue (“Configured”). You’ll see client.connector.installed events in the System Events feed.

Repeat this for each client application you want OneServer to manage.

Adding Your First MCP Server

With a client configured, add an MCP server for it to use:

  1. Discover Panel: On the main dashboard, find a template in the Discover Servers panel (e.g., “Slack Integration”).
  2. Click Add (+): Click the ”+” button on the template card.
  3. Configure & Auto-Discovery: The Right Detail Panel opens (“Add Server from Template”), pre-filled with the template’s details.
    • OneServer automatically starts discovering resources for this template. You’ll see a spinner indicator next to the “Discovering…” text below the Command/URL field.
    • Review and adjust configuration if needed (e.g., add API keys to Environment Variables for the Slack template).
    • Wait for the “Discovering…” indicator to change to “Discovery Successful”.
  4. Explore Discovered Resources (Optional): Expand the sections under Discovered Resources (Tools, Prompts, etc.) to see what capabilities were found on the server.
  5. Save: Once discovery is complete, click the “Save” button. The server will appear in the left sidebar.

Option 2: Adding Manually

  1. Choose Transport & Click Add (+): In the left sidebar, click the ”+” icon next to STDIO or SSE.
  2. Fill Form: In the Right Detail Panel (“Create Server”):
    • Enter a Name.
    • (If STIDO): Enter the full Command and any necessary Environment Variables.
    • (If SSE): Enter the URL. (OAuth is handled automatically if needed).
    • Add an optional Description.
  3. Discover Resources (Required):
    • The “Discover Resources” button ( icon) will be enabled once you provide a Command (for Stdio) or URL (for SSE).
    • Click this button. You’ll see a loading indicator.
    • Wait for the discovery process to complete. The button will return to its normal state, and the Discovered Resources panel below will update with the found capabilities.
    • Important: You must successfully discover at least one capability (tool, prompt, resource, or template) before you can save the server. If discovery fails or finds nothing, you cannot save.
    • If you change the Command or URL after successful discovery, a warning (“Discovery Reset”) will appear, and you will need to click “Discover Resources” again.
  4. Explore Discovered Resources (Optional): Review the discovered items in the panel below the button.
  5. Save: Once discovery is successful and resources are listed, click “Save”.

Associating Server with Client

After adding a server, you need to tell your configured client(s) that they can use it:

  1. Select Client: Click on a client with a Configured status in the left sidebar.
  2. View Details: The Right Detail Panel opens.
  3. Enable Server: Find the “Associated Servers” section. Locate the name of the server you just added and toggle the switch next to it to the ON position.
  4. Confirmation: The association is saved immediately. You’ll see a success toast notification and a client.servers.updated event in the System Events feed.

Your client application can now access the capabilities of the associated server via OneServer!

Installation Usage Guide