Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/organizations/list-organizations/feature.ts:21-124 (handler)

  Core handler function that authenticates with Azure DevOps (PAT or Azure Identity) and fetches the list of accessible organizations via VSSPS APIs.

  export async function listOrganizations(
    config: AzureDevOpsConfig,
  ): Promise<Organization[]> {
    try {
      // Determine auth method and create appropriate authorization header
      let authHeader: string;
  
      if (config.authMethod === AuthenticationMethod.PersonalAccessToken) {
        // PAT authentication
        if (!config.personalAccessToken) {
          throw new AzureDevOpsAuthenticationError(
            'Personal Access Token (PAT) is required when using PAT authentication',
          );
        }
        authHeader = createBasicAuthHeader(config.personalAccessToken);
      } else {
        // Azure Identity authentication (DefaultAzureCredential or AzureCliCredential)
        const credential =
          config.authMethod === AuthenticationMethod.AzureCli
            ? new AzureCliCredential()
            : new DefaultAzureCredential();
  
        const token = await credential.getToken(
          `${AZURE_DEVOPS_RESOURCE_ID}/.default`,
        );
  
        if (!token || !token.token) {
          throw new AzureDevOpsAuthenticationError(
            'Failed to acquire Azure Identity token',
          );
        }
  
        authHeader = `Bearer ${token.token}`;
      }
  
      // Step 1: Get the user profile to get the publicAlias
      const profileResponse = await axios.get(
        'https://app.vssps.visualstudio.com/_apis/profile/profiles/me?api-version=6.0',
        {
          headers: {
            Authorization: authHeader,
            'Content-Type': 'application/json',
          },
        },
      );
  
      // Extract the publicAlias
      const publicAlias = profileResponse.data.publicAlias;
      if (!publicAlias) {
        throw new AzureDevOpsAuthenticationError(
          'Unable to get user publicAlias from profile',
        );
      }
  
      // Step 2: Get organizations using the publicAlias
      const orgsResponse = await axios.get(
        `https://app.vssps.visualstudio.com/_apis/accounts?memberId=${publicAlias}&api-version=6.0`,
        {
          headers: {
            Authorization: authHeader,
            'Content-Type': 'application/json',
          },
        },
      );
  
      // Define the shape of the API response
      interface AzureDevOpsOrganization {
        accountId: string;
        accountName: string;
        accountUri: string;
      }
  
      // Transform the response
      return orgsResponse.data.value.map((org: AzureDevOpsOrganization) => ({
        id: org.accountId,
        name: org.accountName,
        url: org.accountUri,
      }));
    } catch (error) {
      // Handle profile API errors as authentication errors
      if (axios.isAxiosError(error) && error.config?.url?.includes('profile')) {
        throw new AzureDevOpsAuthenticationError(
          `Authentication failed: ${error.toJSON()}`,
        );
      } else if (
        error instanceof Error &&
        (error.message.includes('profile') ||
          error.message.includes('Unauthorized') ||
          error.message.includes('Authentication'))
      ) {
        throw new AzureDevOpsAuthenticationError(
          `Authentication failed: ${error.message}`,
        );
      }
  
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
  
      throw new AzureDevOpsAuthenticationError(
        `Failed to list organizations: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/organizations/schemas.ts:7-7 (schema)

  Input schema for the list_organizations tool (empty object as no parameters are required).

  export const ListOrganizationsSchema = z.object({});

• src/features/organizations/tool-definitions.ts:8-15 (registration)

  Tool definition registration including name, description, and input schema.

  export const organizationsTools: ToolDefinition[] = [
    {
      name: 'list_organizations',
      description:
        'List all Azure DevOps organizations accessible to the current authentication',
      inputSchema: zodToJsonSchema(ListOrganizationsSchema),
    },
  ];

• src/features/organizations/index.ts:39-58 (handler)

  MCP request dispatcher that constructs config from env vars and calls the core listOrganizations handler.

  case 'list_organizations': {
    // Use environment variables for authentication method and PAT
    // This matches how other features handle authentication
    const config: AzureDevOpsConfig = {
      authMethod:
        process.env.AZURE_DEVOPS_AUTH_METHOD?.toLowerCase() === 'pat'
          ? AuthenticationMethod.PersonalAccessToken
          : process.env.AZURE_DEVOPS_AUTH_METHOD?.toLowerCase() ===
              'azure-cli'
            ? AuthenticationMethod.AzureCli
            : AuthenticationMethod.AzureIdentity,
      personalAccessToken: process.env.AZURE_DEVOPS_PAT,
      organizationUrl: connection.serverUrl || '',
    };
  
    const result = await listOrganizations(config);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/features/organizations/index.ts:24-29 (registration)

  Request identifier function that checks if the tool name is 'list_organizations' for routing.

  export const isOrganizationsRequest: RequestIdentifier = (
    request: CallToolRequest,
  ): boolean => {
    const toolName = request.params.name;
    return ['list_organizations'].includes(toolName);
  };