Merge pull request #144 from useshortcut/amcd/handle-gemini-token-issue

Support alternative token name.

Author: andreasmcdermott

README.md

@@ -14,6 +14,64 @@ The MCP server for [Shortcut](https://shortcut.com).
 
 ## Usage
 
+The only required input is your Shortcut API token. You can find it in your [Shortcut account settings](https://app.shortcut.com/settings/account/api-tokens).
+
+Once you have a valid token, you can pass it to the MCP server as an environement variable or a CLI argument.
+
+Examples:
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest"
+  ],
+  "env": {
+    "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
+  }
+}
+```
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest",
+    "SHORTCUT_API_TOKEN=<YOUR_SHORTCUT_API_TOKEN>"
+  ]
+}
+```
+
+Due to an issue in `gemini-cli` that redacts environment variables that contain the word "token", you can also use the alternative name `SHORTCUT_API_TKN` instead of `SHORTCUT_API_TOKEN`. This works for both the environment variable and the CLI argument:
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest"
+  ],
+  "env": {
+    "SHORTCUT_API_TKN": "<YOUR_SHORTCUT_API_TOKEN>"
+  }
+}
+```
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest",
+    "SHORTCUT_API_TKN=<YOUR_SHORTCUT_API_TOKEN>"
+  ]
+}
+```
+
+For more information on how to setup the MCP for your tool of choice, see below.
+
 ### Windsurf
 
 See the [official Windsurf docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more information.
@@ -71,7 +129,6 @@ See the [official Claude Code docs](https://docs.anthropic.com/en/docs/claude-co
 Add the MCP server from the command line:
 
 ```shell
-# Grab your Shortcut token here: https://app.shortcut.com/settings/account/api-tokens
 claude mcp add shortcut --transport stdio -e SHORTCUT_API_TOKEN=$SHORTCUT_API_TOKEN -- npx -y @shortcut/mcp@latest
 ```
 
@@ -319,6 +376,10 @@ You can also check the list of [common issues](#common-issues) below to see if t
 
 ### Common Issues and Solutions
 
+#### MCP fails on startup in Gemini CLI
+
+If you are using the Gemini CLI and the MCP fails with the following error: `✕ Error during discovery for MCP server 'shortcut': MCP error -32000: Connection closed`, it might be due to an issue in Gemini where it redacts environment variables that contain the word `token`. You can either pass the Shortcut token as a CLI argument, or use the alternative name `SHORTCUT_API_TKN` instead of `SHORTCUT_API_TOKEN`. See the [Usage section](#usage) for more information.
+
 #### NPX command not working when using MISE for version management
 
 If you are using MISE for managing Node and NPM versions, you may encounter a "Client closed" error when trying to run the MCP server. Installing this extension into your IDE might help: https://github.com/hverlin/mise-vscode/.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shortcut/mcp",
-	"version": "0.19.0",
+	"version": "0.20.0",
 	"description": "Shortcut MCP Server",
 	"keywords": [
 		"shortcut",

src/server.ts

@@ -12,7 +12,7 @@ import { TeamTools } from "./tools/teams";
 import { UserTools } from "./tools/user";
 import { WorkflowTools } from "./tools/workflows";
 
-let apiToken = process.env.SHORTCUT_API_TOKEN;
+let apiToken = process.env.SHORTCUT_API_TKN || process.env.SHORTCUT_API_TOKEN;
 let isReadonly = process.env.SHORTCUT_READONLY === "true";
 let enabledTools = (process.env.SHORTCUT_TOOLS || "")
 	.split(",")
@@ -25,6 +25,7 @@ if (process.argv.length >= 3) {
 		.slice(2)
 		.map((arg) => arg.split("="))
 		.forEach(([name, value]) => {
+			if (name === "SHORTCUT_API_TKN") apiToken = value;
 			if (name === "SHORTCUT_API_TOKEN") apiToken = value;
 			if (name === "SHORTCUT_READONLY") isReadonly = value === "true";
 			if (name === "SHORTCUT_TOOLS")
@@ -36,7 +37,7 @@ if (process.argv.length >= 3) {
 }
 
 if (!apiToken) {
-	console.error("SHORTCUT_API_TOKEN is required");
+	console.error("A Shortcut api token is required.");
 	process.exit(1);
 }