Authentication

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The GitScrum MCP Server uses OAuth 2.0 Device Authorization Grant (RFC 8628) for authentication. This is the same flow used by smart TVs and CLI tools — you approve access in your browser, and the MCP server receives a token without ever seeing your password.

This approach was chosen specifically for MCP because AI assistants should never handle user credentials directly. The browser-based approval ensures your password stays between you and GitScrum.

How Device Authorization Works

The OAuth 2.0 Device Authorization Grant is designed for devices and applications that cannot open a browser directly. In the MCP context, the "device" is the MCP server running as a local process, and the browser approval happens on your machine.

Why this flow for MCP

Traditional OAuth flows require a redirect URI — the service redirects the browser back to the application after login. MCP servers communicate via stdio (standard input/output) and don't have a web server to receive redirects. The Device Authorization Grant solves this by decoupling the login device (your browser) from the application device (the MCP server).

Key security properties:

• Your password is only entered in the browser, on the GitScrum login page
• The MCP server never sees, stores, or transmits your credentials
• The AI assistant receives only a scoped access token
• Token permissions match your GitScrum account role

Authentication Flow

The complete authentication flow involves four tools and two actors: the AI assistant (which calls MCP tools) and you (who approves in the browser).

Step 1: Initiate login

Tell your AI assistant to log in to GitScrum. The assistant calls the auth_login tool.

You:  "Login to GitScrum"
AI:   Calls auth_login tool

The MCP server contacts the GitScrum authorization server and receives:

• A verification URL where you'll approve access
• A user code that identifies this specific login request
• An expiration time for the code (typically 15 minutes)

The AI assistant displays this information to you:

Open this URL in your browser: https://gitscrum.com/device
Enter this code: ABCD-1234
The code expires in 15 minutes.

Step 2: Browser approval

Open the verification URL in any browser on any device. You'll see a page asking for the user code.

1. Enter the user code exactly as shown (including the hyphen)
2. Sign in to your GitScrum account if you're not already signed in
3. Review the permissions requested by the MCP server
4. Click Approve to authorize access

After approval, the browser shows a confirmation page. You can close the browser tab.

Step 3: Complete authentication

Tell your AI assistant that you've approved the access:

You:  "I've approved the access" or "Complete the GitScrum login"
AI:   Calls auth_complete tool

The MCP server exchanges the device code for an access token and a refresh token. Both are stored locally on your machine.

Step 4: Session active

The AI assistant confirms the session is active:

AI:   "You're authenticated as john@acme.com. You have access to 3 workspaces."

From this point forward, all MCP tool calls are authenticated automatically. You won't need to log in again for this session.

Token Management

Token storage

After successful authentication, tokens are stored locally at:

~/.gitscrum/auth.json

• macOS/Linux: /Users/yourname/.gitscrum/auth.json
• Windows: C:\Users\yourname\.gitscrum\auth.json

The file contains the access token and refresh token. It is created with restricted file permissions (readable only by the current user).

Automatic refresh

Access tokens expire after a set period. When a token expires, the MCP server automatically uses the refresh token to obtain a new access token — no user interaction required.

This happens transparently. You won't see any authentication prompts during normal use. The refresh cycle continues until the refresh token itself expires or you explicitly log out.

Session persistence

Your authentication persists across MCP server restarts. When you restart your AI client (Claude Desktop, VS Code, Cursor), the MCP server reads the stored token from ~/.gitscrum/auth.json and resumes the session automatically.

This means you authenticate once and stay logged in for as long as the refresh token is valid.

Authentication Tools

auth_login

Initiates the Device Authorization Grant flow.

When to use: First-time setup, or after logging out.

What it returns:

• verification_url — URL to open in your browser
• user_code — Code to enter on the verification page
• expires_in — Seconds until the code expires

Example interaction:

You:  "Log in to GitScrum"
AI:   "Open https://gitscrum.com/device and enter code ABCD-1234.
       The code expires in 15 minutes."

auth_complete

Completes the authentication flow after browser approval.

When to use: After you've entered the code and approved access in the browser.

What it returns:

• Authentication status (success or pending)
• User information (name, email)
• Accessible workspaces

Example interaction:

You:  "I approved it"
AI:   "Authenticated as john@acme.com. 3 workspaces available."

If the browser approval hasn't happened yet, auth_complete returns a "pending" status and the AI assistant will let you know.

auth_status

Checks the current authentication state without initiating a login.

When to use: Anytime you want to verify your session is active.

What it returns:

• Whether a valid session exists
• Authenticated user details
• Token validity status

Example interaction:

You:  "Am I logged in to GitScrum?"
AI:   "Yes, authenticated as john@acme.com. Session is active."

auth_logout

Clears all stored authentication tokens.

When to use: When switching accounts, sharing a machine, or ending a session.

What it does:

• Deletes the local token file (~/.gitscrum/auth.json)
• Clears any in-memory token state
• Next MCP call requiring auth will trigger a new login flow

Example interaction:

You:  "Log out of GitScrum"
AI:   "Logged out. Tokens cleared."

Security Considerations

Credentials never reach the AI

The Device Authorization Grant specifically prevents the AI assistant from accessing your credentials. Here's what each actor sees:

The AI assistant knows that authentication succeeded and what workspaces you have access to, but it never handles tokens directly. Tokens exist only in the MCP server process and in the local storage file.

Local storage only

Tokens are stored exclusively on your local filesystem at ~/.gitscrum/auth.json. They are never:

• Sent to AI model providers (Anthropic, OpenAI, etc.)
• Logged to console or output
• Included in AI conversation context
• Transmitted to any third party

Token scope

The access token inherits the permissions of your GitScrum account. If your account has read-only access to certain projects, the MCP server has the same restrictions. The MCP server does not request elevated permissions beyond what your account already has.

Rate limiting on authentication

To prevent brute-force attacks, the authentication endpoint enforces rate limiting:

• Multiple failed device code attempts trigger automatic lockout
• Lockout duration increases with repeated failures
• Successful authentication resets the counter

Multi-Account Usage

Switching accounts

To switch to a different GitScrum account:

1. Tell your AI assistant to log out: "Log out of GitScrum"
2. The stored tokens are cleared
3. Tell your AI assistant to log in: "Log in to GitScrum"
4. Complete the browser flow with the new account

Shared machines

On shared machines, always log out when done. The authlogout tool clears the local token file completely. Verify with authstatus that no session remains active.

Troubleshooting

"Code expired" error

Device codes expire after 15 minutes. If you see this error:

1. Ask the AI assistant to run auth_login again
2. A new code is generated
3. Complete the browser flow promptly

"Authorization pending" after approval

If auth_complete returns "pending" even after you approved in the browser:

• Verify you entered the correct code (check for typos)
• Ensure you clicked the Approve button on the confirmation page
• Wait a few seconds and try auth_complete again — there can be a brief propagation delay

"Unauthorized" errors during use

If you see 401 errors during normal operation:

• The access token may have expired and automatic refresh failed
• Run authlogout followed by authlogin to re-authenticate
• Check that your GitScrum account is still active

Token file permissions

If authentication succeeds but subsequent requests fail, check the token file permissions:

# macOS/Linux
ls -la ~/.gitscrum/auth.json

# Windows (PowerShell)
Get-Acl "$env:USERPROFILE\.gitscrum\auth.json"

The file should be readable only by your user account. If permissions are too restrictive (not readable by you) or too permissive (readable by others), adjust accordingly.

Browser doesn't open automatically

The MCP server displays the URL for you to open manually. It does not attempt to open your browser. Copy the URL and paste it into any browser.

Environment Variable Override

For CI/CD or automated environments where browser-based approval isn't practical, you can bypass the Device Grant flow by setting a token directly:

export GITSCRUM_TOKEN=your-api-token

When GITSCRUM_TOKEN is set, the MCP server uses it directly instead of the stored token file. This is intended for development and automation scenarios — not for regular interactive use.

Security note: Ensure the environment where GITSCRUM_TOKEN is set is secure. Environment variables can be visible to other processes on the same machine.

Next Steps

• Security: Full security model including HTTPS, rate limiting, and error handling.
• Configuration: Client-specific setup for Claude Desktop, GitHub Copilot, Cursor, and more.
• Quick Start: Complete setup walkthrough if you haven't installed yet.
• MCP Overview: All 29 tools and 160+ operations available after authentication.