docs: Added documentation for the new MCP management CLI flags

MCP-Servers.md

@@ -36,6 +36,9 @@ OAuth-protected remote servers are supported natively (see [OAuth Authentication
 
 Every server entry **must** include a `"type"` field set to one of: `"stdio"`, `"http"`, or `"sse"`.
 
+> **Prefer the CLI over hand-editing?** Skip to [Managing MCP Servers from the CLI](#managing-mcp-servers-from-the-cli)
+> for `--mcp-add`, `--mcp-list`, `--mcp-get`, and `--mcp-remove`.
+
 > **Running inside a [Docker Sandbox](Sandboxes)?** MCP servers often need extra network allowances beyond what the base
 > kit provides. See [Sandbox Compatibility](#sandbox-compatibility) at the bottom of this page for details and
 > common gotchas.
@@ -350,6 +353,181 @@ requires you set up some secrets to use it.
 
 For more information about how to set up your vault and inject secrets, please refer to the [Coyote Vault documentation](Vault).
 
+# Managing MCP Servers from the CLI
+
+Coyote provides CLI flags to add, list, inspect, and remove MCP servers without hand-editing `mcp.json`. The flag
+surface mirrors [Claude Code's `claude mcp add`](https://docs.claude.com/en/docs/claude-code/mcp) so muscle memory
+transfers over directly.
+
+## Adding a server
+
+### Stdio (local subprocess)
+
+Use trailing `--` to separate Coyote's flags from the server command:
+
+```shell
+coyote --mcp-add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir
+```
+
+With environment variables:
+
+```shell
+coyote --mcp-add github --env GITHUB_TOKEN={{GITHUB_TOKEN}} \
+  -- docker run -i --rm ghcr.io/github/github-mcp-server
+```
+
+`--env` is repeatable (`--env KEY1=VAL1 --env KEY2=VAL2`). Any value wrapped in `{{NAME}}` is treated as a
+[Vault](Vault) reference: if the secret is not already stored, Coyote will prompt you to add it interactively
+(see [Automatic secret provisioning](#automatic-secret-provisioning) below).
+
+### HTTP (Streamable HTTP)
+
+```shell
+coyote --mcp-add notion --transport http --url https://mcp.notion.com/mcp
+```
+
+With headers for static-token authentication:
+
+```shell
+coyote --mcp-add datadog --transport http \
+  --url https://mcp.datadoghq.com/api/unstable/mcp-server/mcp \
+  --header "Authorization: Bearer {{DATADOG_TOKEN}}"
+```
+
+`--header` is repeatable. For OAuth-protected servers, use `--client-id`, `--callback-port`, and `--redirect-host`
+(see [OAuth Authentication](#oauth-authentication) for background on when each is needed):
+
+```shell
+coyote --mcp-add slack --transport http --url https://mcp.slack.com/mcp \
+  --client-id 1601185624273.8899143856786 --callback-port 3118
+```
+
+### SSE (legacy HTTP+SSE)
+
+```shell
+coyote --mcp-add legacy --transport sse --url http://127.0.0.1:64342/sse
+```
+
+### Transport inference
+
+You can usually omit `--transport`:
+
+- If a trailing `--` command is present, the transport defaults to `stdio`.
+- Otherwise it defaults to `http`.
+
+Pass `--transport` explicitly when adding an `sse` server or when you want to be pedantic.
+
+### Overwriting an existing server
+
+By default, `--mcp-add` prompts before overwriting an entry with the same name. Pass `--mcp-force` to skip the prompt:
+
+```shell
+coyote --mcp-add github --mcp-force -- docker run -i --rm ghcr.io/github/github-mcp-server
+```
+
+## Listing servers
+
+```shell
+coyote --mcp-list
+```
+
+Prints every server from both user and workspace scopes, one line per server with its transport and target. Restrict
+with `--scope`:
+
+```shell
+coyote --mcp-list --scope workspace
+```
+
+## Inspecting a server
+
+```shell
+coyote --mcp-get github
+```
+
+Prints the JSON block for the named server. Coyote searches user scope first, then workspace scope. Use `--scope` to
+restrict:
+
+```shell
+coyote --mcp-get my-db --scope workspace
+```
+
+## Removing a server
+
+```shell
+coyote --mcp-remove github
+```
+
+Prompts before deleting. Skip the prompt with `--mcp-force`:
+
+```shell
+coyote --mcp-remove github --mcp-force
+```
+
+Coyote removes the server from the first scope it's found in (user first, then workspace). Use `--scope` to target
+a specific file.
+
+## Scope
+
+The `--scope` flag controls which file `--mcp-add` / `--mcp-remove` / `--mcp-list` / `--mcp-get` read from or write
+to:
+
+| Value       | File                                                                                          |
+|-------------|-----------------------------------------------------------------------------------------------|
+| `user`      | `~/.config/coyote/functions/mcp.json` (global; the default)                                   |
+| `workspace` | `.coyote/mcp.json` (project-local; created if missing)                                        |
+
+For workspace scope, Coyote reads from the first existing file in the precedence order documented in
+[Workspace-Local MCP Servers](#workspace-local-mcp-servers), and writes to `.coyote/mcp.json` when creating a new file.
+
+## Automatic secret provisioning
+
+Any string value passed to `--env`, `--header`, `--url`, `--client-id`, `--client-secret`, `--cwd`, or
+`--redirect-host` is scanned for `{{NAME}}` [Vault](Vault) references. For each token whose secret isn't already
+in your vault, Coyote will:
+
+1. Print `Value references vault secret {{ NAME }} which is not stored yet.`
+2. Prompt: `Add 'NAME' to the vault now?` (default: yes)
+3. On confirmation, run the standard [vault add-secret](Vault) flow with masked input for the value
+
+The literal `{{NAME}}` token is what gets written to `mcp.json`. Interpolation happens at load time. This means you
+can safely commit a workspace `mcp.json` without exposing secret values.
+
+If you decline a prompt, the add is aborted and no config changes are written.
+
+## Flag reference
+
+| Flag                              | Purpose                                                                            |
+|-----------------------------------|------------------------------------------------------------------------------------|
+| `--mcp-add <NAME>`                | Add a server                                                                       |
+| `--mcp-remove <NAME>`             | Remove a server                                                                    |
+| `--mcp-list`                      | List all servers                                                                   |
+| `--mcp-get <NAME>`                | Show one server's config as JSON                                                   |
+| `--mcp-force`                     | Skip overwrite / removal confirmation                                              |
+| `--transport <stdio\|http\|sse>`  | Explicit transport (inferred if omitted)                                           |
+| `--scope <user\|workspace>`       | Config file to read/write (default: `user`)                                        |
+| `--url <URL>`                     | Endpoint for `http` / `sse` servers                                                |
+| `--env KEY=VALUE`                 | Env var for `stdio` (repeatable)                                                   |
+| `--header "Name: Value"`          | HTTP header for `http` / `sse` (repeatable)                                        |
+| `--cwd <PATH>`                    | Working directory for `stdio`                                                      |
+| `--client-id <ID>`                | OAuth client ID for `http` / `sse`                                                 |
+| `--client-secret <SECRET>`        | OAuth client secret (use `{{NAME}}` to reference a vault secret)                   |
+| `--callback-port <PORT>`          | OAuth callback port                                                                |
+| `--redirect-host <HOST>`          | OAuth redirect host (`127.0.0.1` by default)                                       |
+| `-- <cmd> [args...]`              | Stdio command + args (everything after `--` is passed to the server verbatim)      |
+
+## Notes and caveats
+
+- **`--mcp-list` / `--mcp-get` / `--mcp-remove` / `--mcp-add` are mutually exclusive.** Combining them in one
+  invocation is a parse error.
+- **The trailing `-- <cmd>` is only meaningful for `--mcp-add` with `stdio` transport.** Passing it with `http` or
+  `sse` transport is an error.
+- **Existing behavior change:** because Coyote now supports `--` as a trailing separator, prompt text that literally
+  starts with `-` needs to be quoted or preceded by `--`. This affects only unquoted hyphen-prefixed prompts, which
+  are rare in practice.
+- **OAuth completion is separate from adding.** `--mcp-add` writes the config; you still need
+  `coyote --auth-mcp <NAME>` (or `.mcp auth <NAME>` in the REPL) to complete the OAuth authorization flow the first
+  time.
+
 # Default MCP Servers
 Coyote ships with a `functions/mcp.json` file that includes some useful MCP servers:
 

_Sidebar.md

@@ -33,6 +33,10 @@
 - [Custom Tools](Custom-Tools)
 - [Custom Bash Tools](Custom-Bash-Tools)
 - [MCP Servers](MCP-Servers)
+  - [Managing from CLI](MCP-Servers#managing-mcp-servers-from-the-cli)
+  - [Workspace-Local Servers](MCP-Servers#workspace-local-mcp-servers)
+  - [OAuth Authentication](MCP-Servers#oauth-authentication)
+  - [Sandbox Compatibility](MCP-Servers#sandbox-compatibility)
 
 ## Agents
 - [Agents](Agents)