Azure DevOps MCP Server with PAT Authentication

Instructions

Implementation Reference

• src/tools/core.ts:100-151 (handler)

  Handler function that retrieves Azure DevOps identity IDs based on a search filter using direct API call to identities endpoint.

  async ({ searchFilter }) => {
    try {
      const token = await tokenProvider();
      const connection = await connectionProvider();
      const orgName = connection.serverUrl.split("/")[3];
      const baseUrl = `https://vssps.dev.azure.com/${orgName}/_apis/identities`;
  
      const params = new URLSearchParams({
        "api-version": apiVersion,
        "searchFilter": "General",
        "filterValue": searchFilter,
      });
  
      const response = await fetch(`${baseUrl}?${params}`, {
        headers: {
          "Authorization": `Bearer ${token.token}`,
          "Content-Type": "application/json",
          "User-Agent": userAgentProvider(),
        },
      });
  
      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP ${response.status}: ${errorText}`);
      }
  
      const identities = await response.json();
  
      if (!identities || identities.value?.length === 0) {
        return { content: [{ type: "text", text: "No identities found" }], isError: true };
      }
  
      const identitiesTrimmed = identities.value?.map((identity: IdentityBase) => {
        return {
          id: identity.id,
          displayName: identity.providerDisplayName,
          descriptor: identity.descriptor,
        };
      });
  
      return {
        content: [{ type: "text", text: JSON.stringify(identitiesTrimmed, null, 2) }],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
  
      return {
        content: [{ type: "text", text: `Error fetching identities: ${errorMessage}` }],
        isError: true,
      };
    }
  }

• src/tools/core.ts:97-99 (schema)

  Input schema using Zod for the searchFilter parameter.

  {
    searchFilter: z.string().describe("Search filter (unique namme, display name, email) to retrieve identity IDs for."),
  },

• src/tools/core.ts:94-152 (registration)

  Tool registration using McpServer.tool() with name from CORE_TOOLS, description, schema, and handler.

  server.tool(
    CORE_TOOLS.get_identity_ids,
    "Retrieve Azure DevOps identity IDs for a provided search filter.",
    {
      searchFilter: z.string().describe("Search filter (unique namme, display name, email) to retrieve identity IDs for."),
    },
    async ({ searchFilter }) => {
      try {
        const token = await tokenProvider();
        const connection = await connectionProvider();
        const orgName = connection.serverUrl.split("/")[3];
        const baseUrl = `https://vssps.dev.azure.com/${orgName}/_apis/identities`;
  
        const params = new URLSearchParams({
          "api-version": apiVersion,
          "searchFilter": "General",
          "filterValue": searchFilter,
        });
  
        const response = await fetch(`${baseUrl}?${params}`, {
          headers: {
            "Authorization": `Bearer ${token.token}`,
            "Content-Type": "application/json",
            "User-Agent": userAgentProvider(),
          },
        });
  
        if (!response.ok) {
          const errorText = await response.text();
          throw new Error(`HTTP ${response.status}: ${errorText}`);
        }
  
        const identities = await response.json();
  
        if (!identities || identities.value?.length === 0) {
          return { content: [{ type: "text", text: "No identities found" }], isError: true };
        }
  
        const identitiesTrimmed = identities.value?.map((identity: IdentityBase) => {
          return {
            id: identity.id,
            displayName: identity.providerDisplayName,
            descriptor: identity.descriptor,
          };
        });
  
        return {
          content: [{ type: "text", text: JSON.stringify(identitiesTrimmed, null, 2) }],
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
  
        return {
          content: [{ type: "text", text: `Error fetching identities: ${errorMessage}` }],
          isError: true,
        };
      }
    }
  );

• src/tools/core.ts:13-17 (helper)

  Constant mapping internal tool names to MCP tool names, used in registration.

  const CORE_TOOLS = {
    list_project_teams: "core_list_project_teams",
    list_projects: "core_list_projects",
    get_identity_ids: "core_get_identity_ids",
  };