📌Overview

Purpose: Superargs aims to simplify the configuration of MCP (Model Context Protocol) servers by allowing runtime updates of server arguments during user interactions, enhancing flexibility and reducing setup time.

Overview: Superargs is a middleware solution that dynamically injects arguments into MCP server commands at runtime. This capability permits users to provide necessary details like authentication tokens and environment variables interactively, as opposed to pre-configuring servers. It facilitates the management of MCP servers through an intuitive interface.

Key Features:

Dynamic Arg Injection: Enables the replacement of placeholders in server commands with actual values during runtime, enhancing adaptability.
Customizable Tool Name: Users can rename the argument update tool to align with their workflows, providing better integration.
Comprehensive MCP Support: Supports all requests to the child server including tools, prompts, resources, and messages, ensuring smooth operation of the MCP functionalities.
Change Notifications: Automatically notifies connected clients of any updates to the arguments, maintaining seamless communication and awareness of changes.

Superargs

Superargs allows setting up MCP server arguments during runtime. Provide arguments to any MCP server during interaction with an assistant instead of during initial setup. Whether it’s authentication tokens, environment variables, or other CLI arguments, Superargs makes it easy to provide them during runtime.

Supported by superinterface.ai, supermachine.ai and supercorp.ai.

Installation & Usage

Run Superargs via npx:

npx -y superargs --stdio "npx -y @modelcontextprotocol/server-postgres {{databaseUrl}}"

--stdio: Shell command that runs a stdio MCP server with args to be replaced during runtime in the form {{argName}}.
--update-args-tool-name: (Optional) Custom name for the tool used to update/restart args. Defaults to update_args.

Args

Args in the --stdio command are denoted by {{argName}}. For example:

npx -y superargs --stdio "GITHUB_PERSONAL_ACCESS_TOKEN={{githubToken}} npx -y @modelcontextprotocol/server-github"

In this command:

{{githubToken}} is an arg that can be set at runtime using the update_args tool (or a custom tool name if specified).

Behavior Once Started

Initial state: The MCP server will not have any args set initially.
If the MCP stdio server can start without args, it will start without them and provide tools lists and other MCP server functions. It will include an additional update_args tool to update args.
If the server requires args to start, it will not start until the args are set. Only the update_args tool will be available; all other MCP server functions will return an empty list or an error.
When update_args is used: The server restarts with new args and all MCP server functions become available again.
Tool to Update Args: By default named update_args, allows updating args and restarting the child MCP server.

Examples

GitHub MCP server example:

npx -y superargs --stdio "GITHUB_PERSONAL_ACCESS_TOKEN={{githubToken}} npx -y @modelcontextprotocol/server-github"

SQLite MCP server example:

npx -y superargs --stdio "uv mcp-server-sqlite --db-path={{dbPath}}"

Using with MCP Inspector

Run MCP Inspector with Superargs:
```
npx @modelcontextprotocol/inspector npx -y superargs --stdio "npx -y @modelcontextprotocol/server-postgres {{databaseUrl}}"
```
This command starts Superargs and connects it to MCP Inspector, enabling you to manage your PostgreSQL MCP server through the inspector interface.
Manage MCP Server:

With MCP Inspector, you can list tools, run prompts, access resources, or perform other MCP actions through Superargs.

How It Works

Superargs acts as a middleware wrapper around your MCP server, enabling dynamic injection of args at runtime. It forwards all MCP requests (tools, prompts, resources, messages, roots, etc.) to the underlying child server and introduces an additional tool to manage these args.

Key Features

Dynamic Arg Injection: Replace placeholders in your MCP server command with actual values during runtime.
Customizable Tool Name: Rename the arg update tool via --update-args-tool-name.
Comprehensive MCP Support: Forwards all MCP requests to the child server, including tools, prompts, resources, messages, and roots.
Change Notifications: Notifies clients of changes when args are updated.

Main Use Case

Superargs empowers users to set up and configure MCP servers dynamically during interactions with AI assistants. Instead of requiring pre-configuration of servers with necessary args and credentials, users can provide these details on-the-fly through conversation, enhancing flexibility and reducing setup overhead.

Providing sensitive args securely

Args are passed directly to the child MCP server in the command specified; nothing is stored.

If you want to prevent the LLM from seeing these args, make direct calls to the MCP server through your server client rather than via the assistant.

Why MCP?

Model Context Protocol standardizes how AI tools exchange data. If your MCP server requires dynamic args such as authentication tokens or configuration paths, Superargs allows you to provide them at runtime without altering the server's code. This enables flexible deployments, remote access, and easier debugging.

Contributing

Contributions are welcome! Whether you have ideas for new features, improvements, or encounter issues, please open an issue or submit a pull request.

License

MIT License

Superargs is supported by Superinterface, Supermachine, and Supercorp.