Any MCP client - Spacefast Docs

Any MCP client

Connect any MCP client to Spacefast over hosted HTTP or local stdio, and what sf mcp proxy does.

After this page, you can wire Spacefast into an MCP client that has no first-party plugin, choose between the hosted endpoint and a local stdio server, and know what the CLI’s default proxy lane does.

Pick a transport

Hosted HTTPLocal stdioCLI proxy

The server runs at https://mcp.spacefast.com. Your client signs in with OAuth. There is no filesystem, so publish takes inline files.

{
  "mcpServers": {
    "spacefast": {
      "type": "http",
      "url": "https://mcp.spacefast.com"
    }
  }
}

The "type" field is required. Claude Code rejects a bare { "url": ... } entry outright, and VS Code reads one as a stdio command, so the short form is broken rather than smaller.

The server runs on your machine and can read your working directory, so publish accepts a path.

{
  "mcpServers": {
    "spacefast": {
      "command": "npx",
      "args": ["-y", "spacefast", "mcp"],
      "env": {}
    }
  }
}

Set SPACEFAST_TOKEN in env to authenticate, or leave it empty to publish anonymously and claim the Space later.

The server runs hosted, but your CLI login carries the auth instead of an editor OAuth flow.

{
  "mcpServers": {
    "spacefast": {
      "command": "sf",
      "args": ["mcp", "proxy"]
    }
  }
}

This is what sf setup agent writes by default.

Some clients use different key names. mcp for OpenCode, servers for VS Code, context_servers for Zed, and Amp puts the server map at the top level with no root key at all. sf setup agent knows each dialect, so let it write the file when you can.

Ask the agent to find a documentation page through execute. It should search for the documentation operation, describe it, and call it before attempting a publish.

Hosted authentication

The hosted endpoint is never anonymous. A request with no credential gets a 401 and a WWW-Authenticate challenge that names the protected-resource metadata document. Your client follows that pointer to the authorization server and runs a normal OAuth flow. Bearer and DPoP are both accepted.

The resource identifier is the MCP origin. A Spacefast OAuth token issued for the API rather than for MCP is rejected here.

Your client never holds a Spacefast API token. Each request mints an internal delegation token that lives five minutes and carries exactly the permissions of the credential behind it. Scopes are listed on the MCP server page.

What sf mcp proxy does

sf mcp proxy is a bridge. Your editor speaks stdio to the sf process on your machine, and sf speaks HTTPS to https://mcp.spacefast.com using the login you already have from sf login.

That buys three things:

If you are not logged in, the proxy answers with a JSON-RPC error telling you to run sf login and retry.

Your login is origin-bound. The proxy sends it only to the API and MCP origins of the account that issued it, or to loopback. Pointing --endpoint at some other host fails unless you name that origin with --allow-credential-origin. The endpoint must be HTTPS except on loopback, and may not carry credentials, a query string, or a fragment.

Flag Env What it does
--endpoint SPACEFAST_MCP_URL Remote MCP endpoint. Defaults to the mcp. sibling of your login’s API host
--allow-credential-origin SPACEFAST_MCP_ALLOW_CREDENTIAL_ORIGIN Send your credential to this origin even though it was not issued for it. Repeatable

Each request and response pair is capped at 32 MiB and 30 seconds.

Running the local server directly

sf mcp runs the On-Device server over stdio and hands it the same credential every other CLI command uses. It never writes that credential into client config.

sf mcp
Flag Env What it does
--api-url SPACEFAST_API_URL API base URL for tool calls
--profile SPACEFAST_PROFILE CLI profile to resolve the credential from
--token SPACEFAST_TOKEN Token for tool calls
--workspace-root SPACEFAST_MCP_WORKSPACE_ROOT The one directory publish may read from

Without --workspace-root, the server takes the first file: root your client advertises and falls back to the directory it started in. Setting the flag or the environment variable turns off that discovery.

Diagnostics go to stderr because stdout carries the protocol.

Where each client keeps its config

sf setup agent --agent <id> writes to these paths. ~ is your home directory.

Client Config file
claude-code ~/.claude.json
cursor ~/.cursor/mcp.json
codex ~/.codex/config.toml
vscode <project>/.vscode/mcp.json
github-copilot ~/.copilot/mcp-config.json
devin-desktop ~/.devin/mcp_config.json
zed ~/.config/zed/settings.json
gemini-cli ~/.gemini/settings.json
opencode ~/.config/opencode/opencode.json
amp ~/.config/amp/mcp.json
warp ~/.warp/mcp.json
factory-droid ~/.factory/mcp.json
cline ~/.cline/data/settings/cline_mcp_settings.json
generic <project>/.mcp.json

VS Code is the exception. Its MCP config is project-scoped while every other client’s is global. continue takes skills but no MCP config.

Last updated on September 5, 2026.