feat: Enable Personal Access Token (PAT) authentication support (#1149)

This pull request adds support for authenticating with Azure DevOps
using a Personal Access Token (PAT), in addition to the existing
authentication methods. The implementation includes a new authentication
type, proper handling of PAT tokens, and integration with the Azure
DevOps SDK.

## GitHub issue number
#1146 

## **Associated Risks**

N/A

## ✅ **PR Checklist**

- [x] **I have read the [contribution
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CONTRIBUTING.md)**
- [x] **I have read the [code of conduct
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CODE_OF_CONDUCT.md)**
- [x] Title of the pull request is clear and informative.
- [x] 👌 Code hygiene
- [x] 🔭 Telemetry added, updated, or N/A
- [x] 📄 Documentation added, updated, or N/A
- [x] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**

manual testing on full scoped and partial scoped pats. as well as
expired pats. updated tests

Author: danhellem

src/auth.ts

@@ -78,6 +78,20 @@ class OAuthAuthenticator {
 function createAuthenticator(type: string, tenantId?: string): () => Promise<string> {
   logger.debug(`Creating authenticator of type '${type}' with tenantId='${tenantId ?? "undefined"}'`);
   switch (type) {
+    case "pat":
+      logger.debug(`Authenticator: Using PAT authentication (PERSONAL_ACCESS_TOKEN)`);
+      return async () => {
+        logger.debug(`${type}: Reading token from PERSONAL_ACCESS_TOKEN environment variable`);
+        const b64Pat = process.env["PERSONAL_ACCESS_TOKEN"];
+        if (!b64Pat) {
+          logger.error(`${type}: PERSONAL_ACCESS_TOKEN environment variable is not set or empty`);
+          throw new Error("Environment variable 'PERSONAL_ACCESS_TOKEN' is not set or empty. Please set it with a valid base64-encoded Azure DevOps Personal Access Token.");
+        }
+        // Return base64 value as-is — caller uses it directly as the Basic auth credential
+        logger.debug(`${type}: Successfully retrieved PAT from environment variable`);
+        return b64Pat;
+      };
+
     case "envvar":
       logger.debug(`Authenticator: Using environment variable authentication (ADO_MCP_AUTH_TOKEN)`);
       // Read token from fixed environment variable

src/index.ts

@@ -5,7 +5,7 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { getBearerHandler, WebApi } from "azure-devops-node-api";
+import { getBearerHandler, getPersonalAccessTokenHandler, WebApi } from "azure-devops-node-api";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
@@ -47,7 +47,7 @@ const argv = yargs(hideBin(process.argv))
     alias: "a",
     describe: "Type of authentication to use",
     type: "string",
-    choices: ["interactive", "azcli", "env", "envvar"],
+    choices: ["interactive", "azcli", "env", "envvar", "pat"],
     default: defaultAuthenticationType,
   })
   .option("tenant", {
@@ -64,10 +64,12 @@ const orgUrl = "https://dev.azure.com/" + orgName;
 const domainsManager = new DomainsManager(argv.domains);
 export const enabledDomains = domainsManager.getEnabledDomains();
 
-function getAzureDevOpsClient(getAzureDevOpsToken: () => Promise<string>, userAgentComposer: UserAgentComposer): () => Promise<WebApi> {
+function getAzureDevOpsClient(getAzureDevOpsToken: () => Promise<string>, userAgentComposer: UserAgentComposer, authType: string): () => Promise<WebApi> {
   return async () => {
     const accessToken = await getAzureDevOpsToken();
-    const authHandler = getBearerHandler(accessToken);
+    // For pat, accessToken is base64("{email}:{token}"). Decode to extract the token part,
+    // since getPersonalAccessTokenHandler prepends ":" internally and just needs the raw token.
+    const authHandler = authType === "pat" ? getPersonalAccessTokenHandler(Buffer.from(accessToken, "base64").toString("utf8").split(":").slice(1).join(":")) : getBearerHandler(accessToken);
     const connection = new WebApi(orgUrl, authHandler, undefined, {
       productName: "AzureDevOps.MCP",
       productVersion: packageVersion,
@@ -106,10 +108,27 @@ async function main() {
   const tenantId = (await getOrgTenant(orgName)) ?? argv.tenant;
   const authenticator = createAuthenticator(argv.authentication, tenantId);
 
+  if (argv.authentication === "pat") {
+    const basicValue = await authenticator();
+    // basicValue is already base64("{email}:{token}") — use it directly in the Authorization header
+    const _originalFetch = globalThis.fetch;
+    globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      if (init?.headers) {
+        const headers = new Headers(init.headers as HeadersInit);
+        if (headers.get("Authorization")?.startsWith("Bearer ")) {
+          headers.set("Authorization", `Basic ${basicValue}`);
+          init = { ...init, headers };
+        }
+      }
+      return _originalFetch(input, init);
+    };
+    logger.debug("PAT mode: global fetch interceptor installed to rewrite Bearer -> Basic auth headers");
+  }
+
   // removing prompts untill further notice
   // configurePrompts(server);
 
-  configureAllTools(server, authenticator, getAzureDevOpsClient(authenticator, userAgentComposer), () => userAgentComposer.userAgent, enabledDomains);
+  configureAllTools(server, authenticator, getAzureDevOpsClient(authenticator, userAgentComposer, argv.authentication), () => userAgentComposer.userAgent, enabledDomains);
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

test/src/pat-auth.test.ts

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { describe, expect, it, beforeEach, afterEach } from "@jest/globals";
+import { jest } from "@jest/globals";
+
+jest.mock("../../src/logger.js", () => ({
+  logger: {
+    info: jest.fn(),
+    error: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+jest.mock("@azure/identity", () => ({
+  AzureCliCredential: jest.fn(),
+  ChainedTokenCredential: jest.fn(),
+  DefaultAzureCredential: jest.fn(),
+}));
+
+jest.mock("@azure/msal-node", () => ({
+  PublicClientApplication: jest.fn(),
+}));
+
+jest.mock("open", () => jest.fn());
+
+import { createAuthenticator } from "../../src/auth";
+
+describe("PAT authentication", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe("createAuthenticator('pat')", () => {
+    it("should return the base64 value as-is from PERSONAL_ACCESS_TOKEN", async () => {
+      const b64Pat = Buffer.from("user@example.com:myrawpat").toString("base64");
+      process.env["PERSONAL_ACCESS_TOKEN"] = b64Pat;
+
+      const authenticator = createAuthenticator("pat");
+      const result = await authenticator();
+
+      expect(result).toBe(b64Pat);
+    });
+
+    it("should throw if PERSONAL_ACCESS_TOKEN is not set", async () => {
+      delete process.env["PERSONAL_ACCESS_TOKEN"];
+
+      const authenticator = createAuthenticator("pat");
+
+      await expect(authenticator()).rejects.toThrow("Environment variable 'PERSONAL_ACCESS_TOKEN' is not set or empty");
+    });
+
+    it("should throw if PERSONAL_ACCESS_TOKEN is an empty string", async () => {
+      process.env["PERSONAL_ACCESS_TOKEN"] = "";
+
+      const authenticator = createAuthenticator("pat");
+
+      await expect(authenticator()).rejects.toThrow("Environment variable 'PERSONAL_ACCESS_TOKEN' is not set or empty");
+    });
+
+    it("should return a different value each call if env var changes between calls", async () => {
+      const b64PatA = Buffer.from("user@example.com:token-a").toString("base64");
+      const b64PatB = Buffer.from("user@example.com:token-b").toString("base64");
+
+      process.env["PERSONAL_ACCESS_TOKEN"] = b64PatA;
+      const authenticator = createAuthenticator("pat");
+      const resultA = await authenticator();
+
+      process.env["PERSONAL_ACCESS_TOKEN"] = b64PatB;
+      const resultB = await authenticator();
+
+      expect(resultA).toBe(b64PatA);
+      expect(resultB).toBe(b64PatB);
+    });
+  });
+
+  describe("PAT token extraction for WebApi handler", () => {
+    it("should correctly extract raw PAT from base64(email:pat)", () => {
+      const email = "user@example.com";
+      const rawPat = "myRawPatToken123";
+      const b64 = Buffer.from(`${email}:${rawPat}`).toString("base64");
+
+      const decoded = Buffer.from(b64, "base64").toString("utf8");
+      const extractedPat = decoded.split(":").slice(1).join(":");
+
+      expect(extractedPat).toBe(rawPat);
+    });
+
+    it("should correctly extract raw PAT when PAT itself contains colons", () => {
+      const email = "user@example.com";
+      const rawPat = "part1:part2:part3";
+      const b64 = Buffer.from(`${email}:${rawPat}`).toString("base64");
+
+      const decoded = Buffer.from(b64, "base64").toString("utf8");
+      const extractedPat = decoded.split(":").slice(1).join(":");
+
+      expect(extractedPat).toBe(rawPat);
+    });
+
+    it("should produce a valid Basic auth header value from base64(email:pat)", () => {
+      const email = "user@example.com";
+      const rawPat = "myRawPatToken123";
+      const b64Pat = Buffer.from(`${email}:${rawPat}`).toString("base64");
+
+      // The fetch interceptor uses b64Pat directly as the Basic credential
+      const authHeaderValue = `Basic ${b64Pat}`;
+
+      // Verify the header can be decoded back to the expected credentials
+      const decoded = Buffer.from(b64Pat, "base64").toString("utf8");
+      expect(decoded).toBe(`${email}:${rawPat}`);
+      expect(authHeaderValue).toBe(`Basic ${b64Pat}`);
+    });
+  });
+});