How to add an MCP server to MCPOrbit

To add an MCP server to MCPOrbit, open the app and fill in one short form: a Name, a Type, then a Command and its Arguments for a local server, or a URL for a remote one. There is no config file to edit and nothing to restart. The server's tools appear as soon as it connects.

This is the part that works differently from every other client. Claude Desktop, Cursor, and VS Code each want you to find a JSON file on disk, get its top-level key right, and fully quit the app afterwards. MCPOrbit keeps the connection list itself, so the setup is a form and the server connects while you watch.

One detail catches people out, and it is the only one worth memorizing. Command and Arguments are two separate fields. The program goes in Command. Everything after it goes in Arguments.

Where does MCPOrbit keep its server config?

It does not have one you edit. The other three clients hand you a file path and expect you to keep the JSON valid by hand. MCPOrbit writes your connections to its own data file, mcporbit-data.json, in the application's data directory, and reads them back on launch. You never open it.

That removes two of the three ways this usually fails. A trailing comma cannot break your server list, and there is no top-level key to get wrong. What is left is the server itself, which is the part actually worth your attention.

How do I add my first server in the setup wizard?

On first launch MCPOrbit shows a four-step wizard. Press Get Started, pick a theme, press Next, and you land on a step called Add your first connection.

The form has a Name, a Type, and then either a command or a URL. Type is three buttons: STDIO, HTTP, and SSE. STDIO is the one for a server that runs on your own machine, and it is already selected.

Here are the values for the official filesystem server. It makes a good first server because it needs no setup and no credentials:

Name:       filesystem
Type:       STDIO
Command:    npx
Arguments:  -y @modelcontextprotocol/server-filesystem /Users/you/projects

Add & Continue is greyed out until Name and Command both have something in them. Fill both and it lights up. Press it, then press Start Using MCPOrbit, and the server is in your sidebar.

If you would rather do this later, Skip moves you past the step. The wizard is not the only route in.

How do I add a server after setup?

Press Add Connection at the bottom of the sidebar. It opens the same form with more of it showing.

A local server gains two optional fields: Environment Variables, which takes a JSON object, and Roots, described in the form as the folders offered to the server. A remote server gains Auth, with none, bearer, and apikey. Name and the connection details are the only required parts.

Environment Variables is where a credential belongs. It takes a plain JSON object, the same shape as the env block in a Claude Desktop config:

{
  "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}

The Add Connection button at the bottom of the form follows the same two rules as the wizard. A local server needs a Command. A remote server needs a URL. Miss either and the button stays disabled instead of saving a connection that cannot start.

How do I add a server from the Server Browser?

Server Browser in the sidebar searches a public registry of MCP servers. Open one and it has a Connect section listing every way that server publishes to reach it.

Each option shows its transport as a badge, the address or command as selectable text, a Copy button, and an Add Connection button. If the option needs credentials, the line above the button names them before you commit to anything.

Press Add Connection and the form opens already filled in from the registry record: the name, the transport, the command and its arguments, or the URL and its auth type. Every environment variable the server declares is listed with an empty value, so you get the list of keys without going to find the README. Every field stays editable, so anything the registry got slightly wrong costs a keystroke.

Some servers publish nothing you can connect to. MCPOrbit says so in place of the buttons rather than showing a control that cannot work, and points you at the repository instead.

Should I pick STDIO, HTTP, or SSE?

Pick STDIO when the server runs on your machine. MCPOrbit starts the process itself and talks to it over standard input and output. There is no port and no authentication to arrange, which is why it suits most development work.

Pick HTTP when the server already runs somewhere and you reach it over the network. SSE is the older remote transport, kept for servers that have not moved off it. Both replace Command and Arguments with a single URL field:

Name:  my-remote
Type:  HTTP
URL:   https://mcp.example.com/mcp

For a remote server that needs a token, set Auth to bearer and paste the token below it. That input is masked, so the value does not sit on screen in plain text. If you are choosing between the two transports for a server you are writing, stdio versus Streamable HTTP covers the tradeoff.

Why is Arguments a separate field?

Because a program and its arguments are two different things to the operating system, and MCPOrbit does not put a shell in between. It hands Command to the system as the executable, splits Arguments on spaces, and passes the pieces through as the argument list.

That split is worth knowing about for one reason: there is no quoting. A path with a space in it arrives as two arguments.

Arguments:  -y @modelcontextprotocol/server-filesystem /Users/you/My Projects

The server sees four arguments there, not three. It reads /Users/you/My as the directory and Projects as something extra it was not expecting. Use a path without spaces, or point the server at a symlink you made without one.

How do I know it actually connected?

Pick the connection in the sidebar and its tools appear, each with its description and input schema. The filesystem server publishes fourteen:

read_file, read_text_file, read_media_file, read_multiple_files,
write_file, edit_file, create_directory, list_directory,
list_directory_with_sizes, directory_tree, move_file,
search_files, get_file_info, list_allowed_directories

MCPOrbit puts what the server wrote to stderr next to those tools. That is where a server explains itself, and the filesystem server opens with a line confirming it is up:

Secure MCP Filesystem Server running on stdio

It then reports the directories it will allow, taken straight from its arguments. That is the fastest check that your path arrived intact. If the directory in that line is not the one you typed, the Arguments field is where to look.

Why isn't my server showing up?

Three causes cover almost all of it.

• The whole command line went into Command. Split it: the program in Command, the rest in Arguments.
• A path in Arguments has a space in it. Arguments splits on spaces and does no quoting, so the path arrived in pieces.
• The server writes to standard output. On a STDIO connection that is the protocol channel, and a stray print can corrupt it. Send logs to stderr instead, which how to log from an MCP server walks through.

Adding a server is the short part. What you do next is call the tools by hand, read the schemas the way a model reads them, and find out whether the server behaves before an agent depends on it. That is the whole reason to have a client you drive yourself.