scrumdo-mcp

Connect Claude Code, Codex, Cursor, OpenCode, Antigravity, GitHub Copilot, and other MCP hosts to your ScrumDo / Spryng boards over local stdio.

The default connection is a personal smcp_ token and the collaborate tool profile: read, comment, propose, and follow events as you. A broad organization API key is not equivalent human identity.

Installation

pip install scrumdo-mcp

Requires Python 3.11+. The process speaks MCP over stdio (scrumdo-mcp). That local path is the supported compatibility floor.

The hosted Django endpoint POST https://app.spryng.io/api/scrumdo/organizations/<org>/mcp/rpc/ is a transitional bearer beta. It is not OAuth and is not official Streamable HTTP general availability. Prefer stdio until remote GA.

Get a personal token

1. Sign in at https://app.spryng.io.
2. Open your organization → Settings → MCP Tokens.
3. Create a named personal connection and copy the secret once.

Personal tokens start with smcp_. Do not use Settings → API Tokens (OrgAPIKey) for human AI-client collaboration.

Your org and project slugs are the path segments in app.spryng.io/my-company/engineering.

Local stdio (supported)

Replace the placeholder. Never commit a real token.

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "scrumdo": {
      "command": "scrumdo-mcp",
      "env": {
        "SCRUMDO_TOKEN": "smcp_YOUR_PERSONAL_TOKEN",
        "SCRUMDO_ORG": "your-org-slug",
        "SCRUMDO_PROJECT": "your-default-project-slug",
        "SCRUMDO_BASE_URL": "https://app.spryng.io",
        "SCRUMDO_MCP_PROFILE": "collaborate",
        "SCRUMDO_CLIENT_NAME": "cursor"
      }
    }
  }
}

Claude Code — ~/.claude.json

Same mcpServers shape as Cursor. Prefer the CLI so you do not edit ~/.claude/claude.json by mistake:

claude mcp add scrumdo \
  -e SCRUMDO_TOKEN=smcp_YOUR_PERSONAL_TOKEN \
  -e SCRUMDO_ORG=your-org-slug \
  -e SCRUMDO_PROJECT=your-default-project-slug \
  -e SCRUMDO_BASE_URL=https://app.spryng.io \
  -e SCRUMDO_MCP_PROFILE=collaborate \
  -e SCRUMDO_CLIENT_NAME=claude-code \
  -- scrumdo-mcp

Codex — ~/.codex/config.toml

[mcp_servers.scrumdo]
command = "scrumdo-mcp"

[mcp_servers.scrumdo.env]
SCRUMDO_TOKEN = "smcp_YOUR_PERSONAL_TOKEN"
SCRUMDO_ORG = "your-org-slug"
SCRUMDO_PROJECT = "your-default-project-slug"
SCRUMDO_BASE_URL = "https://app.spryng.io"
SCRUMDO_MCP_PROFILE = "collaborate"
SCRUMDO_CLIENT_NAME = "codex"

Restart Codex after changing the token so the stdio process picks up the new env.

OpenCode — opencode.json

OpenCode uses a top-level mcp object (not mcpServers):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scrumdo": {
      "type": "local",
      "command": ["scrumdo-mcp"],
      "enabled": true,
      "environment": {
        "SCRUMDO_TOKEN": "smcp_YOUR_PERSONAL_TOKEN",
        "SCRUMDO_ORG": "your-org-slug",
        "SCRUMDO_PROJECT": "your-default-project-slug",
        "SCRUMDO_BASE_URL": "https://app.spryng.io",
        "SCRUMDO_MCP_PROFILE": "collaborate",
        "SCRUMDO_CLIENT_NAME": "opencode"
      }
    }
  }
}

Antigravity

Use the same mcpServers shape as Cursor and set SCRUMDO_CLIENT_NAME=antigravity. The connector still enforces the personal smcp_ credential and collaborate profile server-side.

GitHub Copilot Chat — .vscode/mcp.json

Use Copilot Chat in Agent mode with a local stdio server:

{
  "servers": {
    "scrumdo": {
      "type": "stdio",
      "command": "scrumdo-mcp",
      "env": {
        "SCRUMDO_TOKEN": "smcp_YOUR_PERSONAL_TOKEN",
        "SCRUMDO_ORG": "your-org-slug",
        "SCRUMDO_PROJECT": "your-default-project-slug",
        "SCRUMDO_BASE_URL": "https://app.spryng.io",
        "SCRUMDO_MCP_PROFILE": "collaborate",
        "SCRUMDO_CLIENT_NAME": "github-copilot-vscode"
      }
    }
  }
}

GitHub Copilot CLI — ~/.copilot/mcp-config.json

{
  "mcpServers": {
    "scrumdo": {
      "type": "stdio",
      "command": "scrumdo-mcp",
      "args": [],
      "env": {
        "SCRUMDO_TOKEN": "smcp_YOUR_PERSONAL_TOKEN",
        "SCRUMDO_ORG": "your-org-slug",
        "SCRUMDO_PROJECT": "your-default-project-slug",
        "SCRUMDO_BASE_URL": "https://app.spryng.io",
        "SCRUMDO_MCP_PROFILE": "collaborate",
        "SCRUMDO_CLIENT_NAME": "github-copilot-cli"
      }
    }
  }
}

GitHub Copilot cloud agent is not this personal-machine flow. Do not put a person's smcp_ token into a shared repository or organization Agent secret.

Hosted remote (beta, not GA)

You can point a remote-capable host at:

https://app.spryng.io/api/scrumdo/organizations/<org>/mcp/rpc/

with Authorization: Bearer smcp_….

This is the current Workbench bearer JSON-RPC POST. It is not OAuth 2.1, Protected Resource Metadata, or full Streamable HTTP GA. Treat it as beta. Local stdio remains the compatibility floor.

Microsoft 365 Copilot through Copilot Studio is not supported by this beta endpoint. It requires the planned standards-conformant Streamable HTTP endpoint and delegated per-user OAuth; a shared API key is not equivalent human identity.

Tool profiles

Call get_mcp_capabilities() for the exact tool_count and names on your process. This package version registers 56 tools on collaborate and 135 on compat (the previous 133 plus events.wait / events.ack). Compat restores the large surface only when you opt in.

Deprecated / inbox-coupled: wait_for_notifications stays in compat only. New clients should use events.wait / events.ack (connection cursor, independent of the web inbox).

Identity

• Personal smcp_ token → credential_kind=personal_mcp, human collaboration.
• Broad OrgAPIKey → org_api_key. The server refuses to start unless you set SCRUMDO_ALLOW_ORG_API_KEY=1. That flag is an explicit, documented compatibility mode. It does not make the key equivalent to a person.
• SCRUMDO_AGENT_RUN_ID describes a run-scoped session, not human identity.

Events

events.wait(after?, timeout_s, limit) and events.ack(cursor) follow the frozen connection-cursor contract. Envelopes are schema_version 1 with a safe_summary only. If the cursor is behind the 30-day retention floor the adapter returns cursor_expired plus a handoff instruction.

Security

• Create and revoke tokens at Settings → MCP Tokens, not API Tokens.
• The secret is shown once. Do not put a real token in chat, git, tests, or docs.
• Default collaborate omits deletes, webhook admin, org config, secrets, deployment, and direct accepted-spec writes.
• Concurrent writes that this package translates carry Idempotency-Key / expected_version (and If-Match) when callers supply them. Closed error codes include not_found_or_denied, wrong_organization, connection_revoked, grant_required, human_step_up_required, stale_resource, duplicate_command, rate_limited, cursor_expired, unsupported_client_capability.
• Revoke a connection if a machine is lost. The next operation fails.

Environment variables

Legacy SPRYNG_* names are still accepted as aliases.

What you can do (collaborate)

"What cards need my attention?"
"Read ENG-42 and the handoff brief"
"Comment on ENG-42 that the proposal is up"
"Publish this spec as a proposal on ENG-42"
"Wait for the next board event for this connection"

Direct column moves, webhook admin, and accepted-spec overwrites are not on the default profile.

Live conformance (opt-in)

The package includes a stdio-protocol harness (python -m spryng_mcp.conformance). The default hermetic mode launches two real scrumdo-mcp processes against an in-process HTTP fixture. It does not talk to Django.

The two-user live run is opt-in and fail-closed. It never reads tokens from source or fixtures. Export personal smcp_ values only in the process environment (never commit them):

python -m spryng_mcp.conformance hermetic
SCRUMDO_LIVE_CONFORMANCE=1 python -m spryng_mcp.conformance live

If a required live name is missing, the command exits 2 with a missing-fixture message that lists names only.

Development

git clone https://github.com/ScrumDoLLC/scrumdo-mcp.git
cd scrumdo-mcp
pip install -e ".[dev]"
pytest tests/ -v
python -m spryng_mcp.conformance hermetic

License

MIT