feat(mcp): add deapi catalog entry + wire Authorization header for http api_key MCPs

[adampachowicz]

What does this PR do?

Two tightly-coupled commits:

1. fix(mcp): wire the Authorization header for http-transport catalog MCPs using auth.type: api_key. Installing such an MCP (hermes mcp install <name>) prompts for the key and saves it to ~/.hermes/.env, but _build_server_config() emitted only url — no Authorization header — so the saved key was never sent and every tool call failed 401 with no obvious cause. The manual path (hermes mcp add, hermes_cli/mcp_config.py) already writes headers: {Authorization: "Bearer ${VAR}"} resolved by the client's existing env interpolation; this mirrors it in the catalog installer (prefer auth.env_var, else first declared env name, guarded against empty).

This revives #51100 — same diagnosis and fix by @briandevans (credited via Co-authored-by), which was triaged type/bug P2 but closed by its author after ~13 days without review. The difference here: this PR ships the first catalog entry that actually exercises the code path.

2. feat(mcp): add the deapi catalog entry — deAPI's hosted remote MCP (Streamable HTTP, mcp.deapi.ai): image generation (FLUX.2 Klein etc.), TTS, transcription (incl. YouTube/X/Twitch URLs), OCR, video, music, embeddings. 39 tools total; tools.default_enabled curates the 22 real capabilities + account utilities, leaving the 17 *_price estimators opt-in via the install-time checklist. auth: api_key (free $5 signup credit, no card) — the server also advertises OAuth but its AS lacks Dynamic Client Registration today, so api_key is the reliable path (noted in a manifest comment; easy one-commit switch to auth: oauth once DCR lands).

Related Issue

Revives #51100. No existing issue for the deapi entry (searched open/closed issues + PRs for "deapi").

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• 🎯 New skill (bundled or hub) — catalog MCP entry

Changes Made

• hermes_cli/mcp_catalog.py — _build_server_config(): emit headers: {Authorization: "Bearer ${ENV}"} for http + api_key entries
• tests/hermes_cli/test_mcp_catalog.py — test_install_http_api_key_writes_authorization_header (asserts the persisted placeholder is unexpanded in config.yaml and the key landed in .env)
• optional-mcps/deapi/manifest.yaml — new catalog entry

How to Test

1. python -m pytest tests/hermes_cli/test_mcp_catalog.py -q → 36 passed
2. hermes mcp install deapi (get a free key at https://app.deapi.ai) → inspect ~/.hermes/config.yaml:
   mcp_servers.deapi = url + headers.Authorization: Bearer ${DEAPI_API_KEY} + curated tools.include
3. New session: hermes chat -q "Call the deapi get_balance tool" → returns the account balance

Checklist

Code

• I've read the Contributing Guide
• Conventional Commits (fix(mcp):, feat(mcp):)
• Searched existing PRs — fix(mcp): wire Authorization header for http catalog MCPs using api_key auth #51100 is the prior art, closed unreviewed; credited via Co-authored-by
• Only changes related to this fix/feature
• pytest tests/hermes_cli/test_mcp_catalog.py -q — 36 passed
• Test added for the fix
• Tested on my platform: macOS 15 (Darwin 25.5), Hermes v0.18.0

Documentation & Housekeeping

• Docs — manifest comments cover the auth rationale; no repo docs affected — otherwise N/A
• cli-config.yaml.example — N/A
• CONTRIBUTING.md / AGENTS.md — N/A
• Cross-platform — pure Python dict-building, no platform-specific code
• Tool descriptions/schemas — N/A

Screenshots / Logs

Verified end-to-end in a live session (catalog install → new session → MCP tool call):

┊ ⚡ mcp_deapi   0.4s
Your exact balance is 4.967697 USD.
get_available_models returned 25 models.

Disclosure: prepared with AI assistance (Claude Code); diagnosed, reviewed and live-tested by a human.

🤖 Generated with Claude Code

[adampachowicz]

Pushed three follow-up commits addressing packaging and UX gaps found in review of our own PR:

1. fix(packaging) — optional-mcps/deapi added to [tool.setuptools.data-files] so the manifest ships in the wheel (each catalog entry needs its own target, per the comment in pyproject.toml). Side note for maintainers: optional-mcps/unreal-engine appears to be missing its data-files entry too — happy to add it here or in a separate PR if wanted.
2. feat(mcp) — bare hermes mcp add <name> now falls back to the catalog installer when <name> is a shipped entry, so mcp add deapi ≡ mcp install deapi. Explicit --url/--command/--preset still always means a custom server. (+ test)
3. feat(mcp-catalog) — manifests can declare explicit transport.headers (http-only, string→string, ${VAR} resolved by the client at connect time). Explicit headers override the automatic api_key Bearer header from this PR's base fix — covers future X-API-Key-style servers, non-Bearer prefixes and multi-header setups. (+ tests)

Full affected-suite run: pytest tests/hermes_cli/test_mcp_catalog.py tests/hermes_cli/test_mcp_config.py -q → 89 passed. Re-verified E2E locally: hermes mcp add deapi routes to the catalog, installs the correct block, and live get_balance works in a session.

[teknium1]

Thanks for tracing the catalog/manual authentication asymmetry. The core bug is present on current main: hermes_cli/mcp_catalog.py:717-720 saves api_key credentials, while _build_server_config() at hermes_cli/mcp_catalog.py:489-493 emits only url for HTTP entries unless auth is OAuth. The runtime does forward configured headers (tools/mcp_tool.py:2507-2514), and the manual path already persists a Bearer template (hermes_cli/mcp_config.py:485-507).

Problems

• hermes_cli/mcp_catalog.py:83 adds the generic transport.headers schema, but the submitted optional-mcps/deapi/manifest.yaml does not consume it. The verified fix only needs the automatic Bearer template. This broadens the catalog manifest surface without a concrete entry requiring it.

Suggested changes

• Keep the HTTP api_key Bearer-header fix and deapi manifest, but split out transport.headers until a reviewed catalog entry needs a non-Bearer or multi-header scheme.

This is an automated hermes-sweeper review.

[teknium1]

This generic manifest-schema extension is not consumed by the included deapi entry, which uses the automatic Bearer path. Please split it into a focused change when a reviewed catalog MCP actually requires custom/non-Bearer headers.