> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Claude Code

> Work on your app's code locally while your tools still reach its live platform data — data store, tasks, memory, and cross-app.

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.

<Note>
  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](/developer-agent). You'll need a
  local checkout of your repo first — see [GitHub Access](/github-access).
</Note>

<Tip>
  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](/local-claude-code/running-locally).
</Tip>

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

```mermaid theme={null}
flowchart LR
    CC["💻 Local Claude Code"] -- "OAuth (MCP)" --> GW["☁️ Stardeck gateway"]
    GW --> Tools["Data store · Tasks · Memory · Cross-app · Skills"]
```

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](/local-claude-code/tools).

## Before you begin

You'll need:

* A **local checkout** of your app's repository — see [GitHub Access](/github-access)
* **Claude Code** installed on your machine — see [Claude Code](https://www.claude.com/product/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.

<Warning>
  **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.
</Warning>

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):

   ```ini ~/.npmrc theme={null}
   //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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Enable the gateway">
    Flip the toggle on. The connection panel appears.
  </Step>

  <Step title="Copy the .mcp.json snippet">
    Copy the snippet shown in the panel. It looks like this:

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

    <Tip>Copy the snippet straight from the dashboard — the project URL is filled in for you.</Tip>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify the connection">
    Ask Claude something like *"list this project's tasks"*. If you get your project's real tasks back, you're connected.
  </Step>
</Steps>

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

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

```bash theme={null}
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:

```bash theme={null}
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:

```text theme={null}
https://www.stardeck.ai/api/mcp/project/<your-project-id>
```

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

```json theme={null}
{
  "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](#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](/local-claude-code/tools).

## Next steps

<CardGroup cols={2}>
  <Card title="Run Your App Locally" icon="play" href="/local-claude-code/running-locally">
    The other half — boot your app on localhost against your live sandbox
  </Card>

  <Card title="Tools & Permissions" icon="shield" href="/local-claude-code/tools">
    What Claude can do through the gateway, and how your permissions control it
  </Card>

  <Card title="Members & Roles" icon="users" href="/members-and-roles">
    Create and configure the roles that control your access
  </Card>

  <Card title="GitHub Access" icon="github" href="/github-access">
    Get a local checkout of your app's repository
  </Card>

  <Card title="Cross-App Communication" icon="right-left" href="/cross-app/overview">
    How your apps call each other's endpoints
  </Card>
</CardGroup>