`knosh add-mcp`¶

Add an MCP server entry to knosh.json.

Synopsis¶

knosh add-mcp <name> --url <url> [options]
knosh add-mcp <name> --commandLine <command-line> [options]
knosh add-mcp <name> [options] -- <argv>...

Description¶

add-mcp writes a new entry under the mcp key in a Knosh config file. It supports both server types — a "local" server, run as a child process, and a "remote" server, connected over MCP Streamable HTTP — but never asks which type to write: the type is inferred from which input you supplied.

--url makes the server remote.
Trailing argv after --, or --commandLine, makes the server local. Supply exactly one of the two.

There is no --type flag; supplying the wrong combination of options for the inferred type is a usage error, checked before any file is touched.

If the target config file does not already exist, add-mcp creates it. Adding a name that already exists is an error unless --force is given, in which case the existing entry is replaced wholesale.

add-mcp only writes configuration. It does not spawn the local server or connect to the remote URL to confirm it works — use mcp-info for that.

Options¶

--url <url>

The remote server's MCP endpoint. Its presence is what makes the server remote.

--commandLine <command-line> / --command-line <command-line>

The local server's command as a single string, tokenized POSIX-style when the server starts. Mutually exclusive with trailing argv.

(trailing -- <argv>...)

The local server's command as separate argv tokens, given after --. Mutually exclusive with --commandLine. -- is required only when the argv itself contains a dash-leading token (e.g. -y); otherwise it is optional but always accepted.

--env KEY=VALUE

Sets an environment variable for a local server. Repeatable. Requires a local server — supplying --env alongside --url is a usage error. The value may itself contain =; only the first = is treated as the separator.

--header NAME=VALUE

Sets an HTTP header for a remote server. Repeatable. Requires --url — supplying --header for a local server is a usage error. Same =-splitting rule as --env.

--timeoutSeconds <n> / --timeout-seconds <n>

Sets the server's timeout field, in seconds. Must be a positive integer. Applies to both server types.

--required

Sets required: true — a startup failure for this server aborts the run instead of being skipped with a warning.

--disabled

Writes the server with enabled: false.

--global

Targets ~/.config/knosh/knosh.json instead of .knosh.json in the current directory, mirroring init --global.

A local mcp entry merges with the global one per server handle — see mcp — so running add-mcp without --global adds a project-specific server alongside any global ones, rather than displacing them.

--force

Replaces an existing entry with the same name instead of failing.

Output¶

On success, add-mcp names the file it modified and echoes the JSON of the entry it wrote — just the new entry, not the whole file:

Added MCP server 'ksrc' in /Users/you/project/.knosh.json

  "ksrc": {
    "type": "local",
    "command": ["npx", "-y", "ksrc-mcp"]
  }

When --force replaced an existing entry, the first line reads Replaced MCP server '<name>' in <path> instead of Added, so an overwrite is never reported in words that read like a fresh add.

Examples¶

Add a local server using trailing argv:

knosh add-mcp ksrc -- npx -y ksrc-mcp

Add the same server using --commandLine:

knosh add-mcp ksrc --commandLine "npx -y ksrc-mcp"

Add a remote server with a timeout and mark it required:

knosh add-mcp docs --url https://mcp.example.com/v1 --timeoutSeconds 15 --required

Add a remote server with a header, keeping the token out of knosh.json via the {env:NAME} indirection — see header value resolution:

knosh add-mcp docs --url https://mcp.example.com/v1 --header 'Authorization=Bearer {env:DOCS_TOKEN}'

Add a local server to the global config with an environment variable:

knosh add-mcp gh --env GITHUB_TOKEN=ghp_x --global -- npx -y gh-mcp

Replace an existing entry:

knosh add-mcp ksrc --force --commandLine "npx -y ksrc-mcp@latest"

knosh add-mcp¶