Shift MCP Server

Tools

Two tools for multi-agent coordination:

shift_check_in

Register a new worker or update an existing session. Called at the start of every working session.

• Accepts a gist of current work and optional file paths being modified

• Returns a 6-character worker ID, coordination protocol, and the full active workers table

• Pass an existing worker ID to update your session (patch semantics — omitted fields preserved)

• Error responses include the active workers table so agents can self-identify or start fresh

shift_check_out

End a working session and remove from the active worker list.

• Accepts a worker ID and optional summary of what was accomplished

• Idempotent — succeeds silently if the worker ID doesn't exist or was already checked out

Related MCP server: MCP Agent Mail

Resources

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling across all tools

• Structured logging with request-scoped context

• Runs locally (stdio/HTTP) from the same codebase

Coordination-specific:

• In-memory worker session store — no database, no filesystem writes, clears on restart

• Coordination protocol injected on every check-in so agents know how to behave

• Active workers table returned with every response for situational awareness

• Patch semantics on session updates — only provided fields change

Getting Started

MCP Client Config

Add to your MCP client config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "shift": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/shift-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Prerequisites

• Bun v1.2.0 or higher

Installation

git clone https://github.com/cyanheads/shift-mcp-server.git
cd shift-mcp-server
bun install

Configuration

No server-specific environment variables required. Framework defaults:

Running the Server

Local Development

bun run build
bun run start:stdio   # or start:http

Dev mode with watch:

bun run dev:stdio     # or dev:http

Checks and tests:

bun run devcheck      # Lints, formats, type-checks
bun test              # Runs test suite

Docker

docker build -t shift-mcp-server .
docker run -p 3010:3010 shift-mcp-server

Project Structure

Development Guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging

• Register new tools and resources in src/index.ts

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun test

License

Apache-2.0 — see LICENSE for details.