cocalc-api/mcp: refine authentication

Author: haraldschilly

src/packages/conat/hub/api/system.ts

@@ -9,6 +9,7 @@ import { type UserSearchResult } from "@cocalc/util/db-schema/accounts";
 export const system = {
   getCustomize: noAuth,
   ping: noAuth,
+  test: authFirst,
   terminate: authFirst,
   userTracking: authFirst,
   logClientError: authFirst,
@@ -31,6 +32,8 @@ export interface System {
   getCustomize: (fields?: string[]) => Promise<Customize>;
   // ping server and get back the current time
   ping: () => { now: number };
+  // test API key and return scope information (account_id or project_id) and server time
+  test: () => Promise<{ account_id?: string; project_id?: string; server_time: number }>;
   // terminate a service:
   //   - only admin can do this.
   //   - useful for development

src/packages/conat/project/api/system.ts

@@ -28,6 +28,7 @@ export const system = {
   configuration: true,
 
   ping: true,
+  test: true,
   exec: true,
 
   signal: true,
@@ -69,6 +70,8 @@ export interface System {
 
   ping: () => Promise<{ now: number }>;
 
+  test: () => Promise<{ project_id: string; server_time: number }>;
+
   exec: (opts: ExecuteCodeOptions) => Promise<ExecuteCodeOutput>;
 
   signal: (opts: {

src/packages/next/pages/api/conat/project.ts

@@ -58,6 +58,11 @@ export default async function handle(req, res) {
       args,
       timeout,
     });
+    // For project-scoped API keys, include the project_id in the response
+    // so the client can discover it
+    if (project_id0 && !resp.project_id) {
+      resp.project_id = project_id0;
+    }
     res.json(resp);
   } catch (err) {
     res.json({ error: err.message });

src/packages/project/conat/api/system.ts

@@ -2,6 +2,17 @@ export async function ping() {
   return { now: Date.now() };
 }
 
+export async function test({
+  project_id,
+}: {
+  project_id?: string;
+} = {}) {
+  return {
+    project_id: project_id ?? "",
+    server_time: Date.now(),
+  };
+}
+
 export async function terminate() {}
 
 import { handleExecShellCode } from "@cocalc/project/exec_shell_code";

src/packages/server/api/project-bridge.ts

@@ -51,7 +51,12 @@ async function callProject({
     service: "api",
   });
   try {
-    const data = { name, args };
+    // For system.test(), inject project_id into args[0] if not already present
+    let finalArgs = args;
+    if (name === "system.test" && (!args || args.length === 0)) {
+      finalArgs = [{ project_id }];
+    }
+    const data = { name, args: finalArgs };
     // we use waitForInterest because often the project hasn't
     // quite fully started.
     const resp = await client.request(subject, data, {

src/packages/server/conat/api/system.ts

@@ -18,6 +18,26 @@ export function ping() {
   return { now: Date.now() };
 }
 
+export async function test({
+  account_id,
+  project_id,
+}: { account_id?: string; project_id?: string } = {}) {
+  // Return API key scope information and server time
+  // The authFirst decorator determines the scope from the API key and injects
+  // either account_id (for account-scoped keys) or project_id (for project-scoped keys)
+  // into this parameter object.
+  const response: { account_id?: string; project_id?: string; server_time: number } = {
+    server_time: Date.now(),
+  };
+  if (account_id) {
+    response.account_id = account_id;
+  }
+  if (project_id) {
+    response.project_id = project_id;
+  }
+  return response;
+}
+
 export async function terminate() {}
 
 export async function userTracking({

src/python/cocalc-api/Makefile

@@ -11,7 +11,7 @@ help:
 	@echo "  coverage         - Run tests with coverage reporting (HTML + terminal)"
 	@echo "  coverage-report  - Show coverage report in terminal"
 	@echo "  coverage-html    - Generate HTML coverage report only"
-	@echo "  mcp              - Start the MCP server (requires COCALC_API_KEY, COCALC_PROJECT_ID, and COCALC_HOST)"
+	@echo "  mcp              - Start the MCP server (requires COCALC_API_KEY)"
 	@echo "  serve-docs       - Serve documentation locally"
 	@echo "  build-docs       - Build documentation"
 	@echo "  publish          - Build and publish package"

src/python/cocalc-api/src/cocalc_api/api_types.py

@@ -5,6 +5,12 @@ class PingResponse(TypedDict):
     now: int
 
 
+class TestResponse(TypedDict, total=False):
+    account_id: Optional[str]
+    project_id: Optional[str]
+    server_time: int
+
+
 class ExecuteCodeOutput(TypedDict):
     stdout: str
     stderr: str

src/python/cocalc-api/src/cocalc_api/hub.py

@@ -1,7 +1,7 @@
 import httpx
 from typing import Any, Literal, Optional
 from .util import api_method, handle_error
-from .api_types import PingResponse, UserSearchResult, MessageType
+from .api_types import PingResponse, TestResponse, UserSearchResult, MessageType
 from .org import Organizations
 
 
@@ -83,6 +83,19 @@ def ping(self) -> PingResponse:
         """
         raise NotImplementedError
 
+    @api_method("system.test")
+    def test(self) -> TestResponse:
+        """
+        Test the API key and get its scope information.
+
+        Returns:
+            TestResponse: JSON object containing:
+                - account_id (if account-scoped key)
+                - project_id (if project-scoped key)
+                - server_time (current server time in milliseconds since epoch)
+        """
+        raise NotImplementedError
+
     def get_names(self, account_ids: list[str]) -> list[str]:
         """
         Get the displayed names of CoCalc accounts with given IDs.

src/python/cocalc-api/src/cocalc_api/mcp/DEVELOPMENT.md

@@ -10,43 +10,102 @@ Learn more: https://modelcontextprotocol.io/docs/getting-started/intro
 
 ### Required Environment Variables
 
-- **`COCALC_API_KEY`** - API key for CoCalc authentication (format: `sk-...`)
-- **`COCALC_PROJECT_ID`** - UUID of the target CoCalc project
+- **`COCALC_API_KEY`** - API key for CoCalc authentication (format: `sk-...`, can be account-scoped or project-scoped)
 - **`COCALC_HOST`** (optional) - CoCalc instance URL (default: `https://cocalc.com`)
 
 ### Setup Examples
 
-**Local Development:**
+**Local Development (Recommended: Project-Scoped API Key):**
+
+Create a project-scoped API key in your CoCalc project settings:
+
+```bash
+export COCALC_API_KEY="sk-your-project-api-key-here"
+export COCALC_HOST="http://localhost:5000"  # For local CoCalc, or omit for cocalc.com
+uv run cocalc-mcp-server
+```
+
+When started, the server will report:
+
+```
+✓ Connected with project-scoped API key (project: 6e75dbf1-0342-4249-9dce-6b21648656e9)
+```
+
+**Alternative: Account-Scoped API Key:**
+
+Create an account-scoped API key in your CoCalc account settings (Settings → API keys):
+
 ```bash
-export COCALC_API_KEY="sk-your-api-key-here"
-export COCALC_PROJECT_ID="6e75dbf1-0342-4249-9dce-6b21648656e9"
-export COCALC_HOST="http://localhost:5000"  # For local CoCalc
+export COCALC_API_KEY="sk-your-account-api-key-here"
 uv run cocalc-mcp-server
 ```
 
-**Claude Code CLI:**
+When started, the server will report:
+
+```
+✓ Connected with account-scoped API key (account: d0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb)
+```
+
+**Claude Code CLI (Project-Scoped Key - Recommended):**
+
 ```bash
 claude mcp add \
   --transport stdio \
   cocalc \
-  --env COCALC_API_KEY="sk-your-api-key-here" \
-  --env COCALC_PROJECT_ID="6e75dbf1-0342-4249-9dce-6b21648656e9" \
-  --env COCALC_HOST="http://localhost:5000" \
+  --env COCALC_API_KEY="sk-your-project-api-key-here" \
   -- uv --directory /path/to/cocalc-api run cocalc-mcp-server
 ```
 
-**Claude Desktop:**
+**Claude Code CLI (Account-Scoped Key):**
+
+```bash
+claude mcp add \
+  --transport stdio \
+  cocalc \
+  --env COCALC_API_KEY="sk-your-account-api-key-here" \
+  -- uv --directory /path/to/cocalc-api run cocalc-mcp-server
+```
+
+**Claude Desktop (Project-Scoped Key - Recommended):**
+
 Add to `~/.config/Claude/claude_desktop_config.json`:
+
 ```json
 {
   "mcpServers": {
     "cocalc": {
       "command": "uv",
-      "args": ["--directory", "/path/to/cocalc-api", "run", "cocalc-mcp-server"],
+      "args": [
+        "--directory",
+        "/path/to/cocalc-api",
+        "run",
+        "cocalc-mcp-server"
+      ],
       "env": {
-        "COCALC_API_KEY": "sk-your-api-key-here",
-        "COCALC_PROJECT_ID": "6e75dbf1-0342-4249-9dce-6b21648656e9",
-        "COCALC_HOST": "http://localhost:5000"
+        "COCALC_API_KEY": "sk-your-project-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop (Account-Scoped Key):**
+
+Add to `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cocalc": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/cocalc-api",
+        "run",
+        "cocalc-mcp-server"
+      ],
+      "env": {
+        "COCALC_API_KEY": "sk-your-account-api-key-here"
       }
     }
   }
@@ -97,6 +156,7 @@ src/cocalc_api/mcp/
 Execute arbitrary shell commands in the CoCalc project.
 
 **Parameters:**
+
 - `command` (string, required): Command to execute
 - `args` (list, optional): Command arguments
 - `bash` (boolean, optional): Interpret as bash script
@@ -106,6 +166,7 @@ Execute arbitrary shell commands in the CoCalc project.
 **Returns:** stdout, stderr, and exit_code
 
 **Examples:**
+
 ```json
 {"command": "echo 'Hello'"}
 {"command": "python", "args": ["script.py", "--verbose"]}
@@ -121,6 +182,7 @@ Browse project directory structure.
 **URI:** `cocalc://project-files/{path}`
 
 **Parameters:**
+
 - `path` (string, optional): Directory path (default: `.`)
 
 **Returns:** Formatted list of files and directories
@@ -130,6 +192,7 @@ Browse project directory structure.
 ### Adding a New Tool
 
 1. Create `tools/my_tool.py`:
+
 ```python
 def register_my_tool(mcp) -> None:
     """Register my tool with FastMCP instance."""
@@ -143,6 +206,7 @@ def register_my_tool(mcp) -> None:
 ```
 
 2. Update `tools/__init__.py`:
+
 ```python
 def register_tools(mcp) -> None:
     from .exec import register_exec_tool