Security

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 is built on a security-first design philosophy. Every architectural decision prioritizes data safety, controlled access, and protection against accidental or malicious operations through AI assistants. This document covers the complete security model.

Design Philosophy

AI assistants are powerful tools, but they introduce a new category of risk: an AI can execute operations faster and at greater scale than a human clicking through a UI. A misinterpreted instruction like "clean up the old tasks" could have catastrophic consequences if the AI has unrestricted access.

The GitScrum MCP Server addresses this through defense in depth — multiple independent layers of protection that each reduce risk independently. Even if one layer fails, the others prevent data loss or unauthorized access.

Core principles:

• Safe by default. Operations that destroy data are blocked entirely.
• Least privilege. The MCP server only has access to what your GitScrum account can access.
• No secrets in transit. Credentials stay in the browser; tokens stay on your machine.
• Transparent errors. Security failures produce clear, actionable error messages without exposing internals.

Operation Restrictions

CREATE, READ, UPDATE only

The MCP Server enforces a strict operation model. Only three types of operations are permitted:

This restriction applies to all 29 tools and all 160+ operations. There is no tool, action, or parameter combination that can delete data through the MCP server.

Why no DELETE operations

Deleting project data — tasks, sprints, user stories, client records — is an irreversible action with potentially severe consequences. When an AI assistant interprets a natural language instruction, there is always a non-zero probability of misinterpretation. The instruction "remove the old tasks from the backlog" might mean archive, move, or filter — not permanently destroy.

By blocking DELETE at the MCP layer, we eliminate an entire class of risk:

• Misinterpretation. The AI cannot delete data even if it misunderstands the instruction.
• Prompt injection. Malicious prompts cannot trigger data destruction through MCP tools.
• Batch errors. A loop that processes multiple items cannot escalate into mass deletion.
• Accidental scope. "Delete the test task" won't accidentally expand to "delete all tasks."

Destructive operations require the GitScrum web application, where the UI requires explicit human confirmation with visual context of what will be deleted.

Defense in depth

DELETE operations are blocked at multiple independent layers:

1. MCP layer. No DELETE tools exist in the MCP server. The tool schema physically cannot express a delete operation.
2. API layer. The GitScrum API validates request origins and blocks DELETE requests from MCP clients, even if a modified MCP server attempted to send them.
3. Authentication layer. Standard role-based access control applies. Read-only users cannot delete through any channel.

HTTPS-Only Communication

All communication between the MCP server and the GitScrum API uses HTTPS:

• TLS 1.2 minimum. Connections using older TLS versions are rejected.
• Certificate validation enforced. The server validates the API's SSL certificate chain. Self-signed or invalid certificates are rejected.
• No HTTP fallback. The server does not attempt unencrypted HTTP connections under any circumstances.

This ensures that data in transit — tasks, project details, authentication tokens — is encrypted between the MCP server on your machine and the GitScrum API in the cloud.

Local communication

Communication between the AI client (Claude Desktop, VS Code, Cursor) and the MCP server uses stdio (standard input/output). Since both processes run on your local machine, this communication never traverses a network. There is no network-level attack surface for the client-to-server connection.

Authentication Security

OAuth 2.0 Device Authorization Grant

The MCP server authenticates via OAuth 2.0 Device Authorization Grant (RFC 8628). This flow was chosen because:

• No credentials in the MCP server. Your password is entered only in the browser.
• No redirect URI needed. MCP servers communicate via stdio, not HTTP, so traditional OAuth redirect flows don't apply.
• User-visible approval. You see exactly what's being authorized in the browser before approving.

For a detailed walkthrough of the authentication flow, see Authentication.

Token isolation

Authentication tokens exist in exactly two places:

1. In-memory in the MCP server process
2. On-disk at ~/.gitscrum/auth.json

Tokens are never:

• Sent to the AI model provider (Anthropic, OpenAI, etc.)
• Included in AI conversation context or history
• Logged to console, files, or error outputs
• Transmitted to any third-party service

The AI assistant knows that authentication succeeded and which workspaces are available, but it has no access to the token value itself.

Token storage permissions

The token file at ~/.gitscrum/auth.json is created with restricted permissions:

This prevents other users on the same machine from reading your authentication tokens.

Rate Limiting

API rate limits

The GitScrum API enforces rate limits to prevent abuse and ensure fair usage across all clients:

• Requests exceeding the rate limit receive a 429 Too Many Requests response
• The MCP server surfaces rate limit errors to the AI assistant with a clear message
• Rate limits reset automatically after the cooldown period

Authentication rate limiting

Authentication endpoints have additional rate limiting to prevent brute-force attacks:

• Failed device code attempts are counted per client
• Repeated failures trigger automatic lockout with increasing duration
• Successful authentication resets the failure counter

Handling rate limits

When rate-limited, the AI assistant receives a clear error indicating the limit was hit. The recommended approach is to wait before retrying. The MCP server does not automatically retry rate-limited requests, giving the AI assistant full control over retry logic.

Error Handling

Standardized error codes

The MCP server translates API responses into consistent, informative error messages. Each error includes a status code, a human-readable message, and enough context for the AI assistant to either recover or inform the user.

Secure error messages

Error messages are designed to be helpful without exposing sensitive information:

Graceful degradation

When the GitScrum API is unreachable (network issues, maintenance), the MCP server:

1. Returns a clear error to the AI assistant indicating the API is unavailable
2. Does not cache stale data or return outdated results
3. Does not retry automatically, allowing the user to decide when to retry

This ensures you never act on stale project data without knowing it.

No Credential Logging

The MCP server enforces strict rules about what appears in logs and output:

Never logged:

• Passwords (the server never has access to them)
• Authentication tokens (access or refresh)
• API keys
• Personal user data beyond what's in API responses

Logged for debugging (when verbose mode is enabled):

• Tool names and actions called
• API endpoint paths (without authentication headers)
• Error status codes and messages
• Request/response timing

Environment Variables

Two environment variables affect security behavior:

In production use, neither variable should be set. The default configuration routes all traffic to the official GitScrum API over HTTPS.

Best Practices for Enterprise Environments

For developers

• Keep the MCP server updated. Run npx -y @gitscrum-studio/mcp-server to always use the latest version, which includes security patches.
• Log out on shared machines. Always run auth_logout when done on a machine others can access.
• Don't set GITSCRUM_TOKEN in shell profiles. If needed for automation, use a secrets manager or scoped environment.
• Review AI actions. Before confirming operations that modify data, review what the AI assistant proposes.

For workspace administrators

• Use role-based access control. Assign appropriate roles in GitScrum. MCP operations inherit the user's role permissions.
• Monitor the audit log. All MCP operations are logged server-side in the GitScrum activity feed with the user identity.
• Enforce minimum plan requirements. Certain Insights PRO tools require appropriate plan levels.
• Review workspace access. Periodically audit who has access to workspaces and projects.

For security teams

• Source code is open. The MCP server source code is available on GitHub for security review.
• No data persistence. The MCP server stores only the authentication token locally. No project data is cached or written to disk.
• No network listeners. The MCP server communicates via stdio, not network sockets. It does not open ports or accept incoming connections.
• Dependency auditing. Run npm audit against the MCP server's dependency tree for known vulnerabilities.

Vulnerability Reporting

If you discover a security vulnerability in the GitScrum MCP Server, report it privately:

Email: security@gitscrum.com Subject: [SECURITY] MCP Server Vulnerability

Include:

1. Description of the vulnerability
2. Steps to reproduce
3. Potential impact
4. Your contact information

We respond within 48 hours and work with you to address the issue before public disclosure.

Security Checklist

Use this checklist to verify your MCP server deployment is secure:

• [ ] Using the latest version of @gitscrum-studio/mcp-server
• [ ] Node.js version 18+ (includes security patches)
• [ ] Authenticated via browser-based OAuth flow (not environment variable)
• [ ] ~/.gitscrum/auth.json has restricted file permissions
• [ ] GITSCRUM_TOKEN is not set in shell profiles
• [ ] GITSCRUMAPIURL is not set (using default production endpoint)
• [ ] Audit log is reviewed periodically in GitScrum dashboard
• [ ] Workspace roles are assigned appropriately
• [ ] MCP server is run from a trusted local environment

Next Steps

• Authentication: Detailed OAuth 2.0 Device Grant flow and token management.
• Configuration: Client-specific setup and environment variable reference.
• Quick Start: Install and authenticate in under 5 minutes.
• MCP Overview: Full tool reference with all 29 tools and 160+ operations.