mecated: add a one-command `mecated mcp add <URL>` instead of hand-written settings.yaml

Context

While dogfooding Connector Gateway (CGW) from mecated/mecatui, wiring up a single remote MCP server turned out to be far harder than it should be. From the Slack thread between Derek and Jakub:

Attempting to connect by prompting mecatui with a URL, or by running mecated mcp login connector before the server exists in config, fails with:

2026/09/15 14:22:09 ERROR mecated subcommand failed err="MCP server \"connector\" is not configured; add it under mcp.servers[] with auth.mode: oauth"

The only way forward today is to hand-write a block like this into settings.yaml:

mcp:
  mode: global
  servers:
    - name: connector
      url: https://connector-gateway.stacklok.dev/gw/mcp
      auth:
        mode: oauth
        oauth:
          profile: connector
          principal: local-user
          issuer: https://connector-gateway.stacklok.dev
          client: {mode: dcr, dcr: {}}
          scopes: [openid]
          request_refresh_token: false
          credentials:
            mode: local
            local:
              root: /Users/<user>/.config-mecatl/proxy/mcp-credentials
              key_env: MECATL_MCP_CREDENTIAL_KEY
          network: {additional_origins: [], private_origins: [], max_redirects: 0}

…and only then run mecated mcp login connector. Jakub's own summary: "yes, this is complex AF. We should add a simple mecated mcp add <URL> command."

Nearly every field above is either derivable from the URL (issuer, name), a sensible default (scopes, request_refresh_token, network, credentials.root), or discoverable from the server's protected-resource / authorization-server metadata now that direct discovery + DCR landed (#1265).

Problem

• Connecting one remote OAuth MCP server requires ~20 lines of operator YAML with no obvious defaults.
• The config surface is operator-tier, so there is no in-product path at all — the user must leave the harness, edit a file by hand, and restart.
• mecated mcp login SERVER is the only mcp subcommand; it can authorize a server but cannot create one, so it is unreachable for anything not already configured.
• Other harnesses (Claude Code, Codex) let a user attach an MCP server straight from a prompt. Mecatl's split between "operator setting up mecated" and "user using the harness" means the embedded mecatui + mecated case has no equivalent, even though in that case they are the same person on the same machine.

This friction is the main thing blocking day-to-day dogfooding of Connector Gateway from Mecated.

Proposal

1. mecated mcp add <URL> (primary ask)

mecated mcp add https://connector-gateway.stacklok.dev/gw/mcp

Should:

• Derive name from the host (overridable via --name), validating the ASCII [A-Za-z0-9_]+ identifier rule.
• Probe the URL for OAuth protected-resource / authorization-server metadata and pick auth.mode accordingly (none when the server needs no auth, oauth otherwise), deriving issuer and default scopes from discovery rather than asking the operator.
• Default the client to DCR when the issuer advertises a registration endpoint, falling back to a clear error that names the preregistered / cimd alternatives when it does not.
• Default credentials to the local encrypted store under the existing mecatl config root, and default network to the conservative policy (no additional origins, no private origins, zero redirects).
• Write the resulting block into the operator settings.yaml (or print it with --dry-run / --print for operators who manage that file elsewhere, e.g. in a k8s ConfigMap).
• Optionally run the login flow immediately (--login), so the happy path is one command instead of two.

Complementary subcommands worth having in the same shape: mecated mcp list and mecated mcp remove <NAME>.

2. Prompt-driven connect for the embedded mecatui + mecated case

Where mecatui runs against a local, single-user mecated, allow the same add-then-login flow to be initiated from the UI (prompt or /mcp-style command) rather than requiring a manual settings.yaml edit and a restart. This matches what Claude Code and Codex already do and is what was actually attempted in the thread. Remote/multi-tenant deployments should keep the operator-tier restriction — this is explicitly an affordance for the co-located case.

Acceptance criteria

• mecated mcp add <URL> creates a working mcp.servers[] entry for a discovery-capable OAuth MCP server with no other flags required.
• mecated mcp add <URL> --login completes authorization end to end, and tools from that server are listable afterwards.
• Connecting https://connector-gateway.stacklok.dev/gw/mcp requires zero hand-edited YAML.
• mecated mcp list / mecated mcp remove round-trip the entry.
• Failures name the missing piece and the flag that supplies it, instead of a bare "is not configured" error.
• docs/configuration-reference.md is updated — the mcp.servers[].auth.oauth.client.mode row still documents only preregistered and cimd, with no dcr mode, so the config that actually works today is undocumented.
• Documented in docs/usage/ as the recommended way to attach an MCP server.

Related

• #1265 — Direct Streamable HTTP MCP client with discovery and DCR (merged; local DCR support shipped around 0.0.38)
• stacklok/stacklok-enterprise-platform#3843 — /gw/mcp OAuth incompatible with mecatl (worked around, not strictly needed)
• Follow-on from the same thread: mecated's MCP/OAuth logging is too sparse to diagnose a failed connect — Jakub mentioned a patch in progress.