Connect Claude Code - Stardeck Documentation

You can pull your app’s repository and build with Claude Code on your own machine. The catch: some of your app’s building blocks live on the Stardeck platform, not in the repo. Your data store, project tasks, project memory, and cross-app connections aren’t files you can read locally — they’re cloud services. Connecting Claude Code to your organization’s Stardeck MCP server closes that gap. Your local Claude Code can then call those platform services over MCP, and discover Stardeck’s skills and SDK docs, while your files, git history, and terminal stay local.

This is for developing your app’s code on your own machine. For the in-browser builder that writes and deploys code through conversation, see Starcat Developer. You’ll need a local checkout of your repo first — see GitHub Access.

This connects your editor to platform data. To also run your app locally — booted against your live sandbox data store, secrets, and storage — pair it with Run Your App Locally.

How it works

Your local Claude Code connects to your organization’s MCP server on the Stardeck platform, the same connection described in AI Integrations. The platform authenticates you, checks what the connection is allowed to do, and exposes the tools that role can use. A few things worth knowing up front:

One connection per organization — the connection reaches every app in the organization you pick when you authorize. Tools that act on an app take the app’s slug (or id) on each call, so you tell Claude which app you mean, for example “list the open tasks for the storefront app”.
No secret in your files — you authorize once in your browser. The server URL, https://www.stardeck.ai/api/mcp, is the same for everyone, and Claude Code keeps the token out of your config.
You pick the role — when you authorize, you choose an organization role for the connection to act as (from the roles you’re allowed to assign yourself) and read only or read & write access. Tools follow that role, not your own role on the app. See Tools & Permissions.
Managed from your org settings — change the role or access level, or revoke the connection, from Settings → AI Integrations in your organization dashboard.

Before you begin

You’ll need:

A local checkout of your app’s repository — see GitHub Access
Claude Code installed on your machine — see Claude Code
Membership in the organization that owns the app, and an organization role with the agent permissions you need — see Members & Roles

Installing dependencies

Once you have a local checkout, you’ll run npm install to build and run the app. Your app depends on Stardeck’s SDK packages — scoped @stardeck-customer-apps/* (auth, email, payments, data store, and more). These are published to GitHub Packages, and installing them needs a token.

GitHub Packages requires a token for npm installs — even when the packages are public. This is a GitHub limitation, not a Stardeck setting: GitHub’s npm registry authenticates every request, so making the packages public doesn’t enable anonymous installs. (Their container registry allows anonymous pulls; the npm registry never has.) You’ll get a 401 Unauthorized from npm install without one.

To install:

Create a GitHub personal access token with the read:packages scope.

Add it to your ~/.npmrc (keeps the token out of your repo):

~/.npmrc

//npm.pkg.github.com/:_authToken=YOUR_TOKEN
@stardeck-customer-apps:registry=https://npm.pkg.github.com/

Run npm install.

Any GitHub account in the organization that owns the project can issue a token that works — the token only proves who you are, it doesn’t grant extra access.

One-command setup

From the root of your checkout, after npm install, run:

npm run setup

If your app doesn’t have the setup script yet, npx @stardeckai/cli setup does the same thing. This does everything on this page and on Run Your App Locally in one go:

Signs you in to Stardeck in your browser, if you aren’t signed in already.
Shows the coding agents you can connect. The ones installed on your machine are marked detected and already ticked. Use the arrow keys and space to change the selection, then press enter.
Adds the stardeck MCP server to each agent you picked, keeping any other servers you already have.
Pulls your app’s environment into apps/web/.env.local, the same as stardeck env pull.
Tells you how to finish signing in to the MCP server in each agent, such as running /mcp in Claude Code or codex mcp login stardeck in Codex.

Agent	Where the server is added
Claude Code	`.mcp.json` in your checkout
VS Code (GitHub Copilot)	`.vscode/mcp.json` in your checkout
Cursor	`~/.cursor/mcp.json`
Codex	`~/.codex/config.toml`
Gemini CLI	`~/.gemini/settings.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`

Files written inside your checkout are already in your app’s .gitignore. The other agents get the server in your user config, which is fine because the server URL is the same for every app. To skip the picker, name the agents yourself: --agents claude-code,codex. Setup also takes every env pull option, such as --project and --port. You can run it again at any time; agents that are already set up are left as they are. The rest of this page explains how to set things up by hand.

Set it up

Add the server to Claude Code

One connection covers every app in your organization, so add it once for your user:

claude mcp add --transport http --scope user stardeck https://www.stardeck.ai/api/mcp

To limit it to one checkout instead, save this as .mcp.json at the root of that checkout. Stardeck apps keep .mcp.json in .gitignore, so it stays on your machine:

.mcp.json

{
  "mcpServers": {
    "stardeck": {
      "type": "http",
      "url": "https://www.stardeck.ai/api/mcp"
    }
  }
}

Open Claude Code and authorize

Open Claude Code in your checkout, run /mcp, select stardeck, and choose Authenticate (a project .mcp.json asks you to approve the server first). Your browser opens. Sign in, pick the organization that owns the app, pick the role the connection should act as, and choose Read only or Read & write. Pick the least permissive role that covers what you need. Connect Your AI Tool covers the consent screen in detail.

Verify the connection

Ask Claude something like “list the tasks for the storefront app”, using your app’s name. Claude passes the app’s slug to the task tool, and if you get that app’s real tasks back, you’re connected.

Working alongside the Stardeck agent

Keep in mind how the in-product agent treats git: Stardeck agents commit and push their work directly to the main branch. There’s no pull request step — when the agent finishes a change, it lands on main, and that’s what the project’s sandbox builds and runs. That has two implications for local work:

main is shared and live. Pull before you start so you’re not building on a stale tree, and expect the agent (or a teammate) to push to main while you work.
The sandbox doesn’t auto-pull your pushes. Your local edits and branches are invisible to the Stardeck sandbox until they reach main — and even after you push, the sandbox stays on its current commit until you load the new commit into it manually from the dashboard’s git history tab.

Work on a local branch, then merge to main (ideally a squash merge) and push when you want to see the change live. Squashing keeps main’s history readable next to the agent’s direct commits.

git checkout main && git pull          # start from the latest main
git checkout -b my-change              # work on a local branch
# ... edits with Claude Code ...
git checkout main && git pull          # pick up anything the agent pushed
git merge --squash my-change && git commit
git push                               # push to main

After pushing, open the project’s git history tab in the dashboard and load your pushed commit into the sandbox. That’s what brings your change onto the running sandbox so you can test it end to end — pushing alone doesn’t move the sandbox.

Connect other MCP clients

This guide uses Claude Code, but the server is a standard OAuth-based MCP server over Streamable HTTP, and every client uses the same URL: https://www.stardeck.ai/api/mcp. Connect Your AI Tool has setup steps for more clients.

Codex CLI

Add the server to Codex, then start the browser authorization flow:

codex mcp add stardeck --url https://www.stardeck.ai/api/mcp
codex mcp login stardeck

Run codex mcp list or type /mcp in Codex to verify the connection. The server is stored in ~/.codex/config.toml; use a project-scoped .codex/config.toml if you want the connection limited to that checkout.

ChatGPT desktop app

Open Settings → MCP servers → Add server, choose Streamable HTTP, and paste https://www.stardeck.ai/api/mcp. Save, restart ChatGPT if prompted, and select Authenticate for Stardeck. Complete the browser sign-in before asking ChatGPT to list an app’s tasks.

Cursor, Windsurf, Cline, and others

Use the client’s Streamable HTTP MCP configuration with this URL and complete the same browser authorization:

https://www.stardeck.ai/api/mcp

For Cursor, for example, add it to .cursor/mcp.json:

{
  "mcpServers": {
    "stardeck": {
      "type": "http",
      "url": "https://www.stardeck.ai/api/mcp"
    }
  }
}

Switching between apps

The URL is the same for every app, so one connection covers every app in the organization you authorized. Name the app in your request and Claude passes its slug to the tool. To save repeating it, add a line to the repo’s CLAUDE.md such as “This repo is the Stardeck app storefront.” If Claude isn’t sure of the slug, ask it to list your organization’s apps. The connection acts in one organization. If you belong to several and need an app in a different one, authorize again and pick that organization. In Claude Code, open /mcp, select the stardeck server, clear its authentication, and authorize again.

Troubleshooting

No tools show up

Claude Code hasn’t loaded the server yet — run claude mcp list to check it is added (or that .mcp.json is at the repo root), restart Claude Code, then approve the server when prompted.
You haven’t finished the browser authorization — re-open Claude Code and complete the sign-in.
The role you picked holds none of the agent permissions — change the connection’s role in Settings → AI Integrations. The change applies on the next tool call.

A tool you expect is missing

Only a few common tools appear directly in Claude’s tool list. The rest are in Stardeck’s tool catalog, which Claude searches with search_stardeck_tools and runs with execute_stardeck_read_tool or execute_stardeck_write_tool. Ask Claude to search the Stardeck catalog for what you need. If the search doesn’t find it, the connection’s role or access level doesn’t allow it — see Tools & Permissions.

Claude says the app wasn’t found

The app belongs to a different organization than the one you authorized, or the slug is wrong. Ask Claude to list your organization’s apps and use the slug it returns.

`npm install` fails with `401 Unauthorized`

The @stardeck-customer-apps/* packages live on GitHub Packages, which requires a token even though the packages are public. Add a GitHub personal access token with read:packages to your ~/.npmrc — see Installing dependencies.

Authorization fails or returns “unauthorized”

You must be a member of the organization that owns the app, and you must pick that organization during authorization.
The role list only shows roles you’re allowed to assign yourself. If the role you need isn’t there, ask an organization admin.
If your session expired, re-run the authorization flow from Claude Code.

Claude can’t write to the data store

The connection was authorized as Read only, its role lacks data-store write access, or the role has no grant on that store. Data-store writes need agent:data-store:write on the role and Read & write access — see Tools & Permissions.

Next steps

Run Your App Locally

The other half — boot your app on localhost against your live sandbox

Tools & Permissions

What Claude can do on your app, and how the connection’s role controls it

Connect Your AI Tool

The consent screen, other clients, and managing connections

Members & Roles

Create and configure the roles that control your access

GitHub Access

Get a local checkout of your app’s repository

Cross-App Communication

How your apps call each other’s endpoints

​How it works

​Before you begin

​Installing dependencies

​One-command setup

​Set it up

​Working alongside the Stardeck agent

​Connect other MCP clients

​Codex CLI

​ChatGPT desktop app

​Cursor, Windsurf, Cline, and others

​Switching between apps

​Troubleshooting

​No tools show up

​A tool you expect is missing

​Claude says the app wasn’t found

​npm install fails with 401 Unauthorized

​Authorization fails or returns “unauthorized”

​Claude can’t write to the data store

​Next steps

Run Your App Locally

Tools & Permissions

Connect Your AI Tool

Members & Roles

GitHub Access

Cross-App Communication

How it works

Before you begin

Installing dependencies

One-command setup

Set it up

Working alongside the Stardeck agent

Connect other MCP clients

Codex CLI

ChatGPT desktop app

Cursor, Windsurf, Cline, and others

Switching between apps

Troubleshooting

No tools show up

A tool you expect is missing

Claude says the app wasn’t found

`npm install` fails with `401 Unauthorized`

Authorization fails or returns “unauthorized”

Claude can’t write to the data store

Next steps