Quickstart

This guide connects one MCP-capable agent to a Shepherd hub using the published @korso/shepherd MCP server.

Prerequisites

• Node.js 20 or newer.
• An MCP-capable agent client such as Claude Code, Codex, Pi, or another client that can launch a stdio MCP server.
• A Shepherd hub URL and a token for that hub. Korso-hosted users don't need to source these separately — signing in and generating a token from the dashboard hands back both, pre-filled into a ready-to-paste config. Self-hosted users get a HUB_URL and a shared TEAM_TOKEN from whoever runs the hub.

1. Choose your hub

Korso-hosted

1. Sign in to the Korso dashboard with Google or GitHub.
2. Open the Connect Agent panel.
3. Optionally name the token (e.g. "laptop"), then click Generate token.
4. Copy the token immediately — it's shown once and can't be retrieved again.

The panel also shows a ready-to-paste install command for your tool (Claude Code, Codex, Pi, Cursor, or generic JSON), pre-filled with HUB_URL and the new token:

HUB_URL=https://your-shepherd-hub.example.com
SHEPHERD_TOKEN=shp_<your-generated-token>

This token is account-scoped, not workspace-scoped — it works across every workspace your account belongs to, so there's no per-repo or per-workspace re-tokening. The first time your agent opens a repo, it asks which workspace to coordinate that repo with.

You can name, list (with created/last-used timestamps), and individually revoke tokens from the same Connect Agent panel at any time.

Self-hosted

Use the public URL of your hub and the TEAM_TOKEN configured on that hub:

HUB_URL=https://your-shepherd-hub.example.com
TEAM_TOKEN=<your-team-token>

2. Add the MCP server

Shepherd runs as a standard stdio MCP server:

npx -y @korso/shepherd

Most clients need this command plus HUB_URL and your token. For a Korso-hosted hub, use SHEPHERD_TOKEN (the Connect Agent panel generates this for you):

{
  "mcpServers": {
    "shepherd": {
      "command": "npx",
      "args": ["-y", "@korso/shepherd"],
      "env": {
        "HUB_URL": "https://your-shepherd-hub.example.com",
        "SHEPHERD_TOKEN": "shp_<your-generated-token>"
      }
    }
  }
}

For a self-hosted hub, use the same shape with TEAM_TOKEN instead of SHEPHERD_TOKEN.

See Connect your agent for client-specific locations and commands, or Authentication and workspaces for how tokens, workspaces, and repo linking fit together.

3. Restart your client

Restart the agent client after adding the MCP server. Shepherd joins the workspace automatically; there is no join tool to call.

4. Verify the tools are available

Your client should list the four coordination tools:

• work
• done
• announce
• sync

(You'll also see link, unlink, and decline — the repo opt-in tools — until the repo is linked.)

In a fresh session, ask the agent to sync with Shepherd before starting work. A healthy setup returns the current workspace landscape. If the hub cannot be reached, Shepherd reports that the session is proceeding uncoordinated.

Optional identity overrides

Shepherd auto-detects identity from git. Set these only when you need to override the detected values:

A few more variables tune heartbeat timing and the automatic hook install rather than identity — see Connect your agent.

Repository opt-in

A client is installed once and loads for every repo, so each repo makes its own one-time decision to coordinate: a committed .shepherd marker naming the workspace. The normal path is letting the agent's link tool write it — that takes effect immediately, no restart needed. See Authentication and workspaces for the full lifecycle (link / unlink / decline).

If you'd rather commit the marker by hand (e.g. to pre-link a repo before any agent touches it), it's plain JSON with only the workspace slug, never a token:

{ "workspace": "default" }

Unlike the link tool, hand-editing the file isn't picked up by an already-running session — restart the agent's client after adding it.

Troubleshooting