claude-code - 💡(How to fix) Fix Cross-Surface Architecture [2 comments, 2 participants]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Submitted by: Bill Bowman, Bowman Design + Direction Date: 2026-05-05 Repo: anthropic-ai/claude-code Discussions / Feature Request Suggested category: MCP / integration Companion doc: Attached. "replaces an earlier version"

anthropic-multi-surface-architecture-v2.md

Anthropic currently ships multiple products under the single name "Claude" — Claude.ai (web + connectors directory), Claude Desktop, Claude Code (CLI), and Cowork — but they do not share state, permissions, skills, or mental models.

Each surface:

• Registers MCP servers differently
• Manages auth independently
• Stores skills separately
• Has no unified visibility into the others

One name, four products, zero shared mental model.

The result, for advanced users running across all surfaces (which is increasingly common as Cowork, Desktop, and Code each get features the others don't): we are forced to build our own architecture documentation, our own permissions infrastructure, our own cross-surface audit tools — to solve integration and discoverability problems that ideally should be handled by the platform itself.

Specific pain points discovered through trial-and-error (none of these are documented in onboarding):

1. Claude Desktop's claude_desktop_config.json rejects HTTP/SSE MCP entries entirely. Silent rejection error: "The following entries in claude_desktop_config.json are not valid MCP server configurations and were skipped: …" No documented mention of stdio-only requirement. No pre-edit validation. No upgrade path to add HTTP MCPs to Desktop.

2. The same vendor can have three independent auth grants. On my machine, Higgsfield has three separate OAuth/auth states: claude.ai marketplace OAuth (working with credits), local direct-HTTP MCP OAuth (pending), and a vendor CLI auth (used by skills, separate from both MCPs). Three browser flows, three token stores, zero cross-surface awareness.

3. claude mcp list mixes account-level connectors and local MCPs without labels. Account-level connectors (Google Drive, Gmail, Calendar) appear intermixed with local stdio servers (custom MCPs you've registered) with no badge, grouping, or indication of what manages each.

4. Skills exist on two surfaces with no cross-visibility. Claude Desktop has a Skills UI (Customize → Skills). Claude Code has ~/.claude/skills/ and project-level .claude/skills/. They share zero state. Adding a skill to one does not register it in the other. Not a bug — the design — but undocumented.

5. Cowork can't reach local stdio MCPs at all. Documentation suggests Cowork "extends with third-party platforms," but in practice that means HTTP-reachable MCPs only. To bridge Cowork to a local CLI tool, the user must wrap it in an HTTP server, expose it via tunnel (Cloudflare Tunnel, ngrok, etc.), and register the public URL — none of which is in the onboarding flow.

6. The claude.ai connector directory shows "install" for connectors already installed via account-level OAuth. When attempting to install Google Calendar at claude.ai/connectors, the page said it was already installed — but didn't tell me where it was installed from, or how to manage it from the right place.

7. There is no first-class way to audit "what's where." I had to build my own MCP server with a custom tool to see in one place what's registered in Claude Code vs. Claude Desktop, what auth state each is in, and what should-or-shouldn't be mirrored. This should ship with Claude.

I built ~6 systems (permissions manifests, daily briefing dashboard, MCP bridge, cross-client audit tool, ~3,500-word architecture map, video-skill orchestration map) to cope. Total cost: 3 days, several thousand tokens, and ongoing maintenance burden. All of it should have been onboarding.

Proposed Solution

Treat the four surfaces as a first-class architectural concern, not as four products that happen to share a name:

1. Name surfaces clearly in product UI. Pick a convention and use it consistently — "Claude.ai" / "Claude Desktop" / "Claude Code" / "Cowork." When the user looks at "Connectors" or "MCP servers" or "Skills," the surface should be labeled. Largely a copy/UX change, not engineering.

2. Ship a claude surface-status (or equivalent) UI/CLI. Single command, single screen, single source of truth. For each MCP/connector/skill, show: which surface(s) it's registered on, auth state per surface, what the user should do next. (I built a working prototype of this concept; happy to discuss it directly with your team if useful.)

3. Make Claude Desktop's local config schema honest. Either support HTTP MCPs in claude_desktop_config.json OR document explicitly that Desktop is stdio-only with redirect URLs to the marketplace path. The current silent-rejection state is the worst middle ground.

4. Group claude mcp list output by source. Account-level connectors / local stdio / local HTTP — three labeled sections. ~10-line UX change, high-leverage.

5. Show cross-surface auth state even when tokens themselves remain separate. A user with the same vendor authorized on three surfaces should see that fact in one place, even if the auth grants stay independent by design.

6. Onboarding flow that explains the four surfaces. Even a 5-minute walkthrough — "Here's where Claude.ai connectors live. Here's where local Desktop MCPs live. Here's where Code MCPs live. Here's where they overlap." Most users don't need to know this; advanced users absolutely do.

7. Treat skill registration as a first-class cross-surface concern. Either unify Desktop Skills and Code Skills, or document loudly that they are distinct and explain when to use each.

Alternative Solutions

These are the alternatives Anthropic could pick instead of (or as a phased step toward) the proposed solution above:

Alternative A — Documentation only

Don't change any product behavior. Publish the four-surface mental model as official documentation, with examples and diagrams. Lowest engineering cost. Doesn't fix the silent-rejection error or the unlabeled claude mcp list, but at least users discover the architecture without trial-and-error.

Alternative B — Converge surfaces

Deprecate one or more surfaces — most likely Desktop's local config in favor of claude.ai-managed everything, or Code's local MCPs in favor of a unified Anthropic-hosted registry. Strongest unification. Highest disruption to existing users. Probably wrong direction for power users who want local control and multi-agent audit (Codex, etc.).

Alternative C — Acknowledge the split as permanent and provide first-class cross-surface tooling

Don't unify state, but ship official tooling (claude surface-status, surface-labeled output, cross-surface auth visibility) that makes the split easy to navigate. This is the closest to my proposed solution but explicitly accepts the architectural split as a feature, not a bug. Probably the right answer for users who deliberately want the surfaces to remain independent.

Alternative D — Better error messages only

Keep all current architecture, but make every surface boundary fail informatively. Desktop's silent HTTP rejection becomes "HTTP MCPs not supported in Desktop config — see [docs link] to register via Claude.ai connector instead." This is the cheapest path; addresses the symptom (token waste in trial-and-error) without addressing the root cause (no mental model). A reasonable stopgap while the deeper work is scoped.

Alternative E — Status quo

Do nothing. Continue to ship surfaces independently and let advanced users build their own architecture maps. Lowest cost; highest user attrition risk for the persona that builds public documentation about Anthropic's products.

---

My recommendation

The proposed solution above is closest to Alternative C with implementation specifics. Alternative D as a stopgap would buy enormous goodwill while the deeper work is scoped — most of the user pain comes from silent rejections and unlabeled output, not from the underlying architecture itself.

If your team only ships one thing in response to this request: I'd pick Alternative D plus proposed solution item 1 (label surfaces clearly). That's a small engineering investment for outsized reduction in user friction.

---

What I'm offering

The local system I built (MCP bridge, permissions inventory, daily briefing dashboard, cross-surface audit tooling) lives in a private repo. The tooling is not open source, and no public license should be inferred from this submission or any attached materials.

The repo remains private because these systems are currently intertwined with a broader scalable platform architecture and app I'm actively developing. Over time, portions may become more modular or potentially shareable, but today they remain tightly integrated into my operational environment.

I'm open to a direct conversation with Anthropic about the architectural patterns, lessons learned, and ideas described here if any are useful for your roadmap. The tooling and implementation itself remain proprietary, and no rights to use, copy, distribute, or derive from the underlying tooling or implementation are granted through this submission or any attached materials.

The architectural critique itself stands independently of any IP arrangement.

Priority

High - Significant impact on productivity

Feature Category

MCP server integration

Use Case Example

Scenario 1 — Mirroring an MCP from Code to Desktop

A user has an MCP working in Claude Code via local stdio. They want it in Desktop too.

Today: manually edit two config files (~/.claude.json and claude_desktop_config.json), fully quit Desktop (Cmd-Q), troubleshoot why .env didn't load when invoked by Desktop's launcher path.

Proposed: a single claude surface-status command shows current registration; one operation mirrors it.

---

Scenario 2 — Authorizing the same vendor across surfaces

A user has Higgsfield enabled via the claude.ai marketplace connector (working, 3,000 credits). They also register Higgsfield directly in Code for tool-level access. claude mcp list shows "higgsfield: needs authentication" — but they don't realize this is a SECOND independent OAuth grant, separate from the marketplace one.

Confusion: "I already authorized Higgsfield. Why is it asking again?"

Proposed: cross-surface auth visibility tells them "Higgsfield: authorized on marketplace, pending on local — these are independent grants by design."

---

Scenario 3 — Adding an HTTP MCP to Desktop

User reads Claude Code documentation, adds {"type": "http", "url": "..."} to claude_desktop_config.json. Desktop silently rejects with a cryptic error:

"The following entries in claude_desktop_config.json are not valid MCP server configurations and were skipped: ..."

User wastes 30+ minutes debugging.

Proposed: explicit error message redirects user to the marketplace path, OR documents the stdio-only requirement upfront.

---

Scenario 4 — Cross-surface team handoff to Cowork

Team uses Cowork for scheduled morning briefings. They want the same MCP available in Cowork that they use locally in Code. Currently impossible without wrapping the local MCP in an HTTP server, exposing it via Cloudflare Tunnel (or ngrok), and registering the public URL — none of which is in onboarding.

Proposed: documented upgrade path or unified registration model with explicit "this MCP is reachable from: Code, Desktop, Cowork" labels.

---

Scenario 5 — Onboarding a new advanced user

Developer joins a team using Claude across surfaces. Spends 2-3 hours figuring out where MCPs go, why some commands work in Code but not Desktop, where to register a new skill, why their colleague's setup doesn't match theirs.

Proposed: 5-minute walkthrough explaining the four surfaces and where each thing lives, surfaced on first run of any Claude client.

Additional Context

About the submitter: Paying advanced user; designer-founder running a small agency (Bowman Design + Direction). I'm an unusual user persona — I deliberately use Claude.ai for billing and account-level connectors, Claude Desktop for visual orchestration and Cowork-scheduled routines, and Claude Code (CLI) for terminal/builder work, all coordinated via a local-first multi-agent architecture that also includes Codex (OpenAI) for cross-agent code review and audit.

Companion documentation: A longer-form version of this feedback is attached as anthropic-multi-surface-architecture-v2.md. It contains the full McKinsey-style structure with Goals framing, the four-surface table, all seven findings with extended examples, complete ranked recommendations (R1-R8) with reasoning, and an inventory of the local infrastructure I had to build to cope. ~3,500 words.

Reference implementation (private): The local system referenced throughout this submission lives in a private repo. The tooling is not open source. The repo remains private because these systems are currently intertwined with a broader scalable platform architecture and app I’m actively developing. Over time, portions may become more modular or potentially shareable, but today they remain tightly integrated into my operational environment, workflows, and long-term platform direction. The tooling remains proprietary, and no rights to use, copy, distribute, or derive from the underlying implementation are granted through this submission or any companion materials. I'm open to a direct conversation with Anthropic about the architectural patterns and ideas described here if any are useful for your roadmap.

Cost to derive this feedback: ~3 days across multiple Claude Code sessions and several thousand tokens, the majority spent rediscovering boundaries that should have been documented.

The fact that this work fell to a user — rather than being onboarding — is the meta-feedback this request is trying to convey.

No reply expected. This is fire-and-forget. If anything here is worth a deeper conversation, I'm reachable via my public channels at bowmandesign.com.