Skip to content

Fix the Claude Desktop guide: connector first, extension caveats #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
f wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Fix the Claude Desktop guide: connector first, extension caveats #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8b67cbf
Lead the Claude Desktop guide with the Claude plugin marketplace
f Oct 23, 2026
1ef8623
Fix Vale spelling alert and state the 20.3 Node minimum
f Oct 23, 2026
388a56d
Match the agents index card to the Claude Desktop guide
f Oct 23, 2026
50beff3
Quote the manifest's Node range and note the CLI minimum
f Oct 23, 2026
84a72ac
Note the owner requirement for the connector fallback
f Oct 23, 2026
528b06a
Lead the Claude Desktop guide with the connector
f Oct 23, 2026
0c3a1c3
State that the extension publishes inline files on every system
f Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 58 additions & 17 deletions content/agents/claude-desktop.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,77 @@
---
title: Claude Desktop
description: Install the Spacefast desktop extension for Claude Desktop, or paste the hosted MCP server into your config
description: Connect Claude Desktop to Spacefast with the hosted connector, the Spacefast plugin, or the local desktop extension
---

The Spacefast desktop extension lets Claude Desktop publish files and read your Spaces directly.
Add Spacefast to Claude Desktop so it can publish and read your Spaces. The connector is the recommended way. The desktop extension runs the server on your computer instead.

## Install the extension
## Add the Spacefast connector

Download `claude-desktop.mcpb` from the latest release of `github.com/spacefast/plugins` and open it. Claude Desktop installs it as a desktop extension.
The connector is the hosted Spacefast MCP server. You add it once to your Claude account, so it works in the desktop app, on claude.ai, and on your phone.

<Steps>
<Step title="Download the bundle">
Grab `claude-desktop.mcpb` from the releases page.
<Step title="Open Connectors">
On claude.ai or in Claude Desktop, open Customize → Connectors, then choose + → Add custom connector.
</Step>
<Step title="Double-click it">
Claude Desktop reads the manifest and offers to install the extension.
<Step title="Add Spacefast">
Name it Spacefast and use `https://mcp.spacefast.com` as its URL.
</Step>
<Step title="Leave the key blank, or paste one">
The extension has one setting, a Spacefast API key. Leave it empty to publish anonymously and claim the Space later.
<Step title="Connect">
Choose Connect, then sign in to Spacefast and approve access.
</Step>
<Step title="Turn it on">
Turn Spacefast on for the conversation you want to use it in.
</Step>
</Steps>

Then ask for something small to prove the extension is live.
On a Team or Enterprise plan, an owner has to add the connector first.

<Prompt description="Publish this folder to Spacefast and give me the live URL." actions={["copy"]}>
Publish this folder to Spacefast and give me the live URL.
Then ask for something small to prove Spacefast is connected.

<Prompt description="Make a one-page site and publish it to Spacefast." actions={["copy"]}>
Make a one-page site that says hello and publish it to Spacefast. Give me the link.
</Prompt>

<Prompt description="List my Spacefast Spaces." actions={["copy"]}>
List my Spacefast Spaces.
</Prompt>

## Add the Spacefast plugin

The plugin adds the Spacefast skills and the hosted connector to your Claude account, for the Chat and Cowork tabs and for Claude Code signed in with the same account.

<Steps>
<Step title="Open the Plugins page">
In Claude, open Customize → Plugins, then choose Add → Add marketplace → Add from a repository.
</Step>
<Step title="Add the Spacefast marketplace">
Paste `spacefast/plugins` and add the marketplace.
</Step>
<Step title="Add the plugin">
Select the Spacefast plugin, then choose Add.
</Step>
</Steps>

If Claude says the Spacefast connector isn't connected, add the connector as described above. Plugins need a paid Claude plan, and on a Team or Enterprise plan an owner may limit which marketplaces you can add. See [Use plugins in Claude](https://support.claude.com/en/articles/13837440-use-plugins-in-claude).

## Install the desktop extension

The extension runs the Spacefast MCP server on your computer. It publishes inline files on every system; to publish a local folder, use the [CLI](/cli) (`sf publish <path>`). It starts the server with `npx`, so it needs Node.js 20.3 or newer with `npx` installed where Claude Desktop can find it.

<Steps>
<Step title="Download the bundle">
Download `claude-desktop.mcpb` from the latest release of `github.com/spacefast/plugins`.
</Step>
<Step title="Double-click it">
Claude Desktop reads the manifest and offers to install the extension.
</Step>
<Step title="Leave the key blank, or paste one">
The extension has one setting, a Spacefast API key. Leave it empty to publish anonymously and claim the Space later.
</Step>
</Steps>

If Claude Desktop shows "Server disconnected" or "Unable to connect to extension server", open `~/Library/Logs/Claude/mcp-server-Spacefast.log` on macOS. `spawn npx ENOENT` means Claude Desktop cannot find `npx`. This happens when Node.js comes from Homebrew or a Node version manager. Use the connector instead.

## What the manifest declares

The bundle is a manifest version `0.2` extension with a Node server. Its entry point is `server/index.js`, which is a thin spawner. It launches the Spacefast MCP server over stdio through `npx`, so the extension itself carries no server code.
Expand All @@ -45,14 +86,14 @@ The bundle is a manifest version `0.2` extension with a Node server. Its entry p
}
```

Because the server runs locally, it can read files. `publish` takes a path or the current directory, not only inline files.
The server runs locally, but it starts through `npx`, so `publish` takes inline files on every system. Use the CLI for a local folder.

| Fact | Value |
|---|---|
| Manifest version | `0.2` |
| Server type | `node` |
| Platforms | macOS, Windows, Linux |
| Node | 20 or newer |
| Node | 20 or newer (the CLI it launches needs 20.3 or newer) |
| License | MIT |
| Tools declared | The nine Spacefast MCP tools |

Expand Down Expand Up @@ -83,8 +124,8 @@ If you would rather connect to the hosted endpoint and sign in with OAuth, add t
}
```

The hosted server has no filesystem, so `publish` requires inline files. Connectors you add on claude.ai sync down to Desktop; the bundle is the desktop-only lane.
The hosted server has no filesystem, so `publish` requires inline files. Plugins and connectors you add to your Claude account sync down to Desktop; the bundle is the desktop-only lane.

:::note
`sf setup agent --agent claude-desktop` writes nothing. Claude Desktop is not one of the clients the CLI knows how to configure. Use the extension or the config file above.
`sf setup agent --agent claude-desktop` writes nothing. Claude Desktop is not one of the clients the CLI knows how to configure. Use the plugin, the extension, or the config file above.
:::
2 changes: 1 addition & 1 deletion content/agents/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ The default connection method is `remote-proxy`, which points your client at `sf
Plugin with an always-available rule, or a one-click deeplink.
</Card>
<Card title="Claude Desktop" href="/agents/claude-desktop" icon="monitor">
A double-click desktop extension with an optional token field.
The hosted connector, the Spacefast plugin, or a local desktop extension.
</Card>
<Card title="Any other MCP client" href="/agents/other-clients" icon="plug">
The stdio command, the hosted URL, and generic JSON config.
Expand Down
Loading