Superargs

Dynamically inject runtime args to an MCP server, enabling on-the-fly authentication, config, and actions.

javascript

68

GitHub Stars

javascript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "supercorp-ai-superargs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "{{databaseUrl}}"
      ]
    }
  }
}

Superargs lets you provide runtime arguments to an MCP server on demand, so you can authenticate, configure environment variables, or pass other CLI options without preconfiguring them at startup. It acts as a runtime wrapper around the underlying MCP server and exposes a dedicated tool to update arguments and restart the server when needed.

How to use

Use Superargs to start an MCP server that can receive dynamic runtime arguments. You run Superargs with a stdio mode command so the actual MCP server receives its arguments at runtime. The runtime values are provided through a dedicated tool that restarts the child MCP server with the updated arguments. After you start it, all standard MCP endpoints (tools, prompts, resources, messages, roots, etc.) are forwarded to the underlying server. If the server requires arguments to start, it won’t become accessible until you supply them via the update tool.

Key concepts you’ll use:
- A stdio-based startup that wraps the MCP server command and exposes a runtime-arg update tool (default name is update_args).
- The ability to supply placeholders like {{argName}} in the startup command, which you replace at runtime with real values through the update tool.
- The option to rename the update tool to fit your workflow via --update-args-tool-name.

Typical workflow:

Start the Superargs wrapper with a stdio MCP server command that includes runtime placeholders.
If the underlying server can operate without arguments, you’ll get a working tool list and features while the update_args tool remains available to inject values later.
When you need to provide credentials or configuration, run the update_args tool to restart the child server with the new values.
Connect your MCP client or inspector to manage tools, prompts, and resources as the server becomes fully available after the restart.

How to install

Prerequisites you need before installation:
- Node.js (recommended LTS version)
- npm (comes with Node.js) or npx available in your environment
- Basic command-line usage familiarity for running npx and interpreting runtime placeholders.

Install and start a runtime-MCP server via Superargs with the following command. This example uses a PostgreSQL-backed MCP server as the runtime target:

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

Additional sections

Security and runtime considerations: Args are passed to the child MCP server through the command you provide. They are not stored by Superargs. If you don’t want the runtime values to be visible to the assistant, call the MCP server directly from your own client code instead of routing it through the assistant.

Examples of runtime configurations you can supply include authentication tokens, database URLs, or environment paths. You can customize the update tool name with --update-args-tool-name to better fit your workflow.

With MCP Inspector, you can manage your running MCP server, list tools, run prompts, and access resources through the wrapper interface. This gives you a convenient UI to interact with both the Superargs wrapper and the underlying MCP server.

Available tools

update_args

Tool to update runtime arguments for the MCP server and restart the child server.

MCP Inspector

Interface to manage MCP servers, list tools, run prompts, access resources, and monitor server state through the inspector UI.