From 48d42bec0b9981d7409990decfd535c1feda328d Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Wed, 12 Aug 2026 17:47:44 -0600 Subject: [PATCH] docs: Added documentation for the new MCP management CLI flags --- MCP-Servers.md | 178 +++++++++++++++++++++++++++++++++++++++++++++++++ _Sidebar.md | 4 ++ 2 files changed, 182 insertions(+) diff --git a/MCP-Servers.md b/MCP-Servers.md index 50f18c1..8ee265f 100644 --- a/MCP-Servers.md +++ b/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 ` | Add a server | +| `--mcp-remove ` | Remove a server | +| `--mcp-list` | List all servers | +| `--mcp-get ` | Show one server's config as JSON | +| `--mcp-force` | Skip overwrite / removal confirmation | +| `--transport ` | Explicit transport (inferred if omitted) | +| `--scope ` | Config file to read/write (default: `user`) | +| `--url ` | Endpoint for `http` / `sse` servers | +| `--env KEY=VALUE` | Env var for `stdio` (repeatable) | +| `--header "Name: Value"` | HTTP header for `http` / `sse` (repeatable) | +| `--cwd ` | Working directory for `stdio` | +| `--client-id ` | OAuth client ID for `http` / `sse` | +| `--client-secret ` | OAuth client secret (use `{{NAME}}` to reference a vault secret) | +| `--callback-port ` | OAuth callback port | +| `--redirect-host ` | OAuth redirect host (`127.0.0.1` by default) | +| `-- [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 `-- ` 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 ` (or `.mcp auth ` 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: diff --git a/_Sidebar.md b/_Sidebar.md index 8e749f8..2f2ff69 100644 --- a/_Sidebar.md +++ b/_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)