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. The Claude Code gateway closes that gap. Turn it on and your local Claude Code can call those platform services over MCP — and discover Stardeck’s skills and SDK docs — while your files, git history, and terminal stay entirely 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 a project-scoped endpoint on the Stardeck platform. The platform authenticates you, checks what the connection is allowed to do, and exposes a focused set of tools. A few things worth knowing up front:

One project per connection — the endpoint is tied to a single project, so the tools always act on the right app.
No secret in your files — you authorize once in your browser. The .mcp.json you add to your repo contains only the project URL, never a token.
Off by default — the gateway is disabled until you enable it for a project.
Same access as the project agent — the gateway connects with your permissions on the project — the same access the in-product project agent has for you. There is no separate gateway role to pick. See Tools & Permissions.

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
Access to the project’s Settings in the Stardeck dashboard

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.

Set it up

Open the project's Integrations settings

In the dashboard, open your app, go to Settings, and select the Integrations tab. Find the Claude Code section.

Enable the gateway

Flip the toggle on. The connection panel appears.

Copy the .mcp.json snippet

Copy the snippet shown in the panel. It looks like this:

.mcp.json

{
  "mcpServers": {
    "stardeck": {
      "type": "http",
      "url": "https://www.stardeck.ai/api/mcp/project/<your-project-id>"
    }
  }
}

Copy the snippet straight from the dashboard — the project URL is filled in for you.

Add it to your repo

Save the snippet as .mcp.json at the root of your local checkout. Claude Code only loads it when you’re working in that folder, so the tools are scoped to that project automatically.

Open Claude Code and authorize

Open Claude Code in the project folder. It detects the new server and asks you to approve it, then opens your browser to sign in once. After you authorize, the tools become available.

Verify the connection

Ask Claude something like “list this project’s tasks”. If you get your project’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

Claude Code is the first-class path for this project guide, but the endpoint is a standard OAuth-based MCP server over Streamable HTTP. Other clients can use the same project URL shown in the dashboard.

Codex CLI

Add the project endpoint to Codex, then start the browser authorization flow:

codex mcp add stardeck --url https://www.stardeck.ai/api/mcp/project/<your-project-id>
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 the project URL. Save, restart ChatGPT if prompted, and select Authenticate for Stardeck. Complete the browser sign-in before asking ChatGPT to list the project’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/project/<your-project-id>

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

{
  "mcpServers": {
    "stardeck": {
      "type": "http",
      "url": "https://www.stardeck.ai/api/mcp/project/<your-project-id>"
    }
  }
}

Switching between projects

Each project gets its own URL, and the .mcp.json lives in that project’s repo. Moving between apps is just a matter of changing directories: open the checkout for the app you want to work on and Claude Code picks up that project’s tools. The server is always named stardeck, so prompts and skills that reference it stay portable across your apps.

Troubleshooting

No tools show up

The gateway is off for this project — enable it in Settings → Integrations.
Claude Code hasn’t loaded the server yet — make sure .mcp.json is at the repo root and 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.

`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 project, and you must sign in to that organization during authorization.
If your session expired, re-run the authorization flow from Claude Code.

Claude can’t write to the data store

Your role doesn’t grant data-store access on this project, or the app has no data store connected. Data-store tools (read and write) require data-store access on your role — 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 through the gateway, and how your permissions control it

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

​Set it up

​Working alongside the Stardeck agent

​Connect other MCP clients

​Codex CLI

​ChatGPT desktop app

​Cursor, Windsurf, Cline, and others

​Switching between projects

​Troubleshooting

​No tools show up

​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

Members & Roles

GitHub Access

Cross-App Communication

How it works

Before you begin

Installing dependencies

Set it up

Working alongside the Stardeck agent

Connect other MCP clients

Codex CLI

ChatGPT desktop app

Cursor, Windsurf, Cline, and others

Switching between projects

Troubleshooting

No tools show up

`npm install` fails with `401 Unauthorized`

Authorization fails or returns “unauthorized”

Claude can’t write to the data store

Next steps