Skip to content

Connect Claude Code to Stellary

Read your cards and documents from Claude Code through MCP. For a coding mission launched from Stellary, connect Desktop to the local repository and follow the result in the card.

Create a projectOpen the local AI guide
Claude Code · local runner or MCP client

Claude Code

Connected

Stellary

Launch workspace

Ready
Project context
Prepare release mission
Activity
Identity, project, and tools remain scoped

From project context to a first Claude Code mission

MCP gives the client access to the project. Desktop lets Stellary launch a mission in the linked repository. Choose the path that matches your task.

  1. 01

    Install

    Install and authenticate Claude Code on the machine that owns the repository.

  2. 02

    Connect

    Open Stellary Desktop and refresh the local runner catalog.

  3. 03

    Link

    Attach the local Git folder to the matching Stellary project.

  4. 04

    Assign

    Select Claude Code as the agent execution target and launch a card mission.

  5. 05

    Review

    Follow progress, questions, completion, or failure from Activity.

Mission STL-128

Install and authenticate Claude Code on the machine that owns the repository.

Running

Checklist

Connect
Link
Assign

Linked context

project-brief.md

Run Claude Code on the connected machine in the repository linked to the Stellary project.

Run mission

Claude Code works from the card, not a pasted prompt

The local runner receives the mission and linked repository through the configured project. MCP offers a second path for interactive access to project objects and tools.

Local repository execution

Run Claude Code on the connected machine in the repository linked to the Stellary project.

Mission context

Keep the card, checklist, linked documents, rules, and expected outcome attached to the execution.

Visible return path

Progress, questions, cancellation, failure, and final output return to the mission Activity.

Claude Code MCP connection with OAuth

Shell

In Claude Code, open /mcp and authenticate Stellary in the browser. Select the workspace and access you need.

claude mcp add --transport http stellary https://api.stellary.co/mcp
claude mcp list

Alternative: MCP token

JSON

Project .mcp.json configuration. Set STELLARY_MCP_TOKEN in the client environment before starting it. A projects:read personal token is enough to explore the project as yourself; an agent mission needs the appropriate identity and permissions.

{
  "mcpServers": {
    "stellary": {
      "type": "http",
      "url": "https://api.stellary.co/mcp",
      "headers": {
        "Authorization": "Bearer ${STELLARY_MCP_TOKEN}"
      }
    }
  }
}

Configuration documentation checked on .

Sources and terms to review

Prepare the client and project

Install a recent Claude Code version and check that its help includes the MCP commands above. Your AI provider account and your Stellary connection are separate credentials.

Create a Stellary project with a test card, a precise objective, and a context document. Reading this data through MCP does not require a local repository or Desktop.

Verify MCP with a read operation

After OAuth consent, open /mcp in the client and check that Stellary is available. Ask: “Call stellary_init, list the projects I can access, then summarize the test card’s acceptance criteria. Do not modify any objects.”

The check succeeds when the client finds the right project and the criteria actually written in the card. Use IDs returned by list_projects for subsequent calls. Adding a server to configuration does not prove this access.

Prepare a first mission with Desktop

To launch Claude Code from a card, install and authenticate its CLI on the repository machine. In Stellary Desktop, refresh the runners, share the available runner with the workspace, then link the exact Git folder to the project.

Configure an agent for local execution with Claude Code. Prepare a card: “Read the README and repository scripts. Propose a verification plan with the relevant commands, without changing files.” Launch the mission and wait for its result in the card Activity.

  • The machine is connected and the runner is ready.
  • The trace identifies the expected project and repository.
  • The result cites the files inspected and distinguishes proposed commands from executed tests.
  • A person reviews the result before starting a code change.

Troubleshoot a failed connection

A 401 response indicates missing, expired, or revoked access. Reconnect OAuth, or check the token and environment variable in the client process.

For a 403 response, check scopes, role, and project access. If a tool is not advertised, also check the selected identity and the agent tool policy.

  • For Claude Code, use --transport http in the command; include type: http in JSON.
  • If Desktop cannot see the runner, check its installation and sign-in on that machine, then refresh.
  • If a mission stays queued, check the machine, runner sharing, linked repository, and agent target.

Understand where the work runs

A remote MCP connection gives access to the hosted project. A Desktop mission runs on the connected machine; this does not mean the AI model runs locally.

The model provider can receive the context needed for the request and apply its own access or billing terms. Check the selected model and allowed data before sending a sensitive document.

Which Claude Code connection should you use?

Primary job

Local runner

Work inside the linked repository.

Remote MCP

Operate on live Stellary project data.

Execution location

Local runner

Your connected desktop machine.

Remote MCP

Any compatible MCP client environment.

Identity

Local runner

Configured workspace agent and machine.

Remote MCP

OAuth identity, personal access token, or agent token.

Best starting point

Local runner

Coding mission from a card.

Remote MCP

Explore projects or run an external agent loop.

Questions about Claude Code and Stellary

Can Claude Code modify a repository from Stellary?

Yes, through the connected Stellary Desktop runner when the target project has a linked local repository and the agent is configured for local execution.

Does Claude Code need MCP for local missions?

You do not need to manually add the remote server to launch a Desktop mission. The MCP configuration above connects your own Claude Code session to Stellary tools.

What happens if the machine is offline?

An offline, paused, or disconnected machine cannot claim a local mission. The workspace keeps the mission state visible instead of silently pretending execution started.

Can Claude Code writes require approval?

Workspace writes made with an agent token follow the agent autonomy policy. In approval mode, non-read tools become proposals for human review.

Continue the setup

Local AI apps guideMachines, repositories, shared models, and agent setup.Project management MCP serverIdentity, transport, tools, missions, and approvals.AI Kanban boardFollow Claude Code missions from the shared board.

Run one Claude Code mission from a real card

Connect the machine, link the repository, and keep the result in the project Activity.

Create a Stellary project