Skip to main content
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 the Developer Agent. You’ll need a local checkout of your repo first — see GitHub Access.

​
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.
  • You stay in control of access — you pick a role that decides exactly what Claude can do. 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
  • A role to assign the connection — 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:
  1. Create a GitHub personal access token with the read:packages scope.
  2. 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/
  3. 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

1

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.
2

Enable the gateway

Flip the toggle on. The connection panel appears.
3

Choose the role Claude operates as

Under “Claude operates as”, pick a role. Its permissions decide which tools Claude gets — for example, whether it can write to your data store or only read. Without a role, Claude only gets project tasks and memory. See Tools & Permissions for the full mapping, and assign the least access that gets the job done.
4

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.
5

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.
6

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.
7

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.

​
Other MCP clients

Claude Code is the first-class path, but the endpoint is a standard OAuth-based MCP server over HTTP. Any MCP client that speaks the same protocol — Cursor, Windsurf, Cline, and others — can connect using the same URL. Add it to that client’s MCP configuration and complete the browser authorization the same way.

​
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

The role you selected under “Claude operates as” doesn’t grant write access. Pick a role with the right permissions — see Tools & Permissions.

​
Next steps

Tools & Permissions

What Claude can do through the gateway, and how the role controls it

Members & Roles

Create and configure the role Claude operates as

GitHub Access

Get a local checkout of your app’s repository

Cross-App Communication

How your apps call each other’s endpoints