Companion

Companion is a macOS/iOS/visionOS utility designed to help you test and debug MCP servers by connecting to them, inspecting their prompts, resources, and tools, and invoking actions directly from a graphical interface. It does not itself run as an MCP server; instead, it acts as a client to connect to local or remote MCP servers, browse what they offer, and execute tools or generate prompts with arguments. Once you add a server, Companion will automatically connect and present sections for prompts, resources, and tools so you can drill into individual items and test interactions against your MCP server.

To use Companion, first add a server by clicking the + button in the toolbar and providing the server command (as required by the MCP server you’re testing) and any necessary connection details. After a successful connection, you can navigate through the server’s available prompts to see how they behave, view resources the server exposes, and access tools that can be called with specific arguments. This makes it convenient to validate server behavior, experiment with prompts, and download resources for further testing or verification. If you’re looking for more advanced MCP debugging capabilities, you can also explore the MCP Inspector for comparison and tooling guidance.

Prerequisites:

• macOS 15 or later
• Xcode 16.3 or later (for macOS/iOS tooling as needed)

Install options:

1. Download direct:

   • Obtain the Companion app from the latest release archive: https://github.com/mattt/Companion/releases/latest/download/Companion.zip

2. Install via Homebrew (recommended for macOS users):

   brew install --cask mattt/tap/Companion
   

Usage after installation:

• Launch the Companion app from your Applications folder.
• Use the + button in the toolbar to add an MCP server by providing the appropriate server command and connection details.
• Once a server connects, explore prompts, resources, and tools to test interactions and verify behavior.

Notes:

• Companion is in early development and does not yet include features like authentication, roots, or sampling. It is designed primarily as a debugging aid and interface for MCP servers.

Tips and common issues:

• Companion is a GUI client for MCP servers and does not host a server itself. Use it to connect to your local or remote MCP servers.
• If you’re using an external server command (for example, from iMCP or another tool), copy the command to your clipboard and paste it into the Command field for your STDIO server configuration within Companion.
• Be aware that authentication, roots, and sampling features may be missing or incomplete in this early development release.
• Check for updates to Companion and the MCP tools you are testing to ensure compatibility with the latest MCP protocol changes.
• If you encounter connection issues, verify network access and ensure the server is listening on the expected address/port and that any required environment variables or credentials are configured in the server side configuration.

Environment variables and configuration options you might encounter when testing MCP servers:

• SERVER_COMMAND: the shell command used to start the MCP server
• SERVER_ARGS: any additional arguments required to launch the server
• MCP_HOST / MCP_PORT: host and port for connecting to the MCP server
• AUTH_TOKEN or similar: placeholder for future authentication mechanisms (not required in early builds)